better public interface and doxygen

3 files changed, 106 insertions, 4 deletions

diff --git a/examples/hello.c b/examples/hello.c
new file mode 100644
index 0000000..67ac88b
--- /dev/null
+++ b/examples/hello.c
@@ -0,0 +1,102 @@
+/* A complete CPU-rendered window. Build instructions: docs/getting-started.md. */
+#include <yasl/yasl.h>
+
+#include <stdio.h>
+#include <string.h>
+
+struct app {
+    bool running;
+    bool failed;
+    bool smoke_test;
+};
+
+static void quit(void *ud)
+{
+    ((struct app *)ud)->running = false;
+}
+
+static void lost(void *ud)
+{
+    struct app *app = ud;
+    app->failed = true;
+    app->running = false;
+}
+
+static void close_window(struct yasl_surface *surface, void *ud)
+{
+    (void)surface;
+    quit(ud);
+}
+
+static void configure(struct yasl_surface *surface, struct yasl_geometry geometry, void *ud)
+{
+    (void)geometry;
+    (void)ud;
+    yasl_surface_schedule_redraw(surface);
+}
+
+static void draw(struct yasl_surface *surface, struct yasl_frame *frame, void *ud)
+{
+    struct app *app = ud;
+    size_t count = (size_t)frame->target.size.x * frame->target.size.y;
+    for (size_t i = 0; i < count; i++)
+        frame->target.pixels[i] = 0xff306090; /* Opaque premultiplied ARGB. */
+
+    struct yasl_damage_list damage = {.n = -1};
+    if (!yasl_surface_present(surface, &frame->target, &damage)) {
+        fprintf(stderr, "Could not present the draw target\n");
+        app->failed = true;
+        app->running = false;
+    }
+    if (app->smoke_test) app->running = false;
+}
+
+int main(int argc, char **argv)
+{
+    struct app app = {.running = true};
+    if (argc == 2 && strcmp(argv[1], "--smoke-test") == 0)
+        app.smoke_test = true;
+    else if (argc != 1) {
+        fprintf(stderr, "Usage: %s [--smoke-test]\n", argv[0]);
+        return 1;
+    }
+
+    struct yasl_display_cbs display_callbacks = {.quit = quit, .lost = lost};
+    struct yasl_display_spec display_spec = {
+        .app_id = "org.example.hello",
+        .cbs = &display_callbacks,
+        .ud = &app,
+    };
+    struct yasl_display *display = yasl_display_open(NULL, &display_spec);
+    if (!display) {
+        perror("yasl_display_open");
+        return 1;
+    }
+    struct yasl_surface_spec spec = {.title = "Hello YASL", .size = {640, 480}};
+    struct yasl_surface *surface = yasl_surface_create_toplevel(display, &spec);
+    if (!surface) {
+        perror("yasl_surface_create_toplevel");
+        yasl_display_close(display);
+        return 1;
+    }
+    struct yasl_surface_cbs callbacks = {
+        .draw = draw, .configure = configure, .close = close_window,
+    };
+    yasl_surface_set_callbacks(surface, &callbacks, &app);
+    yasl_surface_schedule_redraw(surface);
+
+    while (app.running) {
+        if (yasl_display_dispatch(display, -1) < 0) {
+            perror("yasl_display_dispatch");
+            app.failed = true;
+            break;
+        }
+        /* Drain even unused input so queued events do not cause a busy loop. */
+        struct yasl_input_event event;
+        while (yasl_surface_input_poll(surface, &event)) {}
+        if (app.running) yasl_display_flush(display);
+    }
+    yasl_surface_destroy(surface);
+    yasl_display_close(display);
+    return app.failed ? 1 : 0;
+}
diff --git a/examples/simple_window.c b/examples/simple_window.c
index 40a7c25..85db04a 100644
--- a/examples/simple_window.c
+++ b/examples/simple_window.c
@@ -152,9 +152,9 @@ int main(void)
         while (yasl_surface_input_poll(s, &ev)) {
             if (ev.kind == YASL_INPUT_KEY) {
                 if (ev.key.action == YASL_KEY_PRESS) {
-                    if (ev.key.key == 0xff1b) { /* Escape */
+                    if (ev.key.key == YASL_KEY_ESCAPE) { /* Escape */
                         running = false;
-                    } else if (ev.key.key == ' ' || ev.key.key == 0xff0d) { /* Space or Return */
+                    } else if (ev.key.key == YASL_KEY_SPACE || ev.key.key == YASL_KEY_ENTER) { /* Space or Return */
                         color_theme++;
                         yasl_surface_schedule_redraw(s);
                     }
diff --git a/examples/tablet.c b/examples/tablet.c
index 4d7a8bd..0aae370 100644
--- a/examples/tablet.c
+++ b/examples/tablet.c
@@ -148,8 +148,8 @@ static void input(struct app *app, const struct yasl_input_event *event)
         (event->kind == YASL_INPUT_FOCUS && !event->focus.focused)) {
         cancel_stroke(app);
     } else if (event->kind == YASL_INPUT_KEY && event->key.action == YASL_KEY_PRESS) {
-        if (event->key.key == 0xff1b) app->running = false;
-        if (event->key.key == 'c' || event->key.key == 'C' || event->key.key == ' ')
+        if (event->key.key == YASL_KEY_ESCAPE) app->running = false;
+        if (event->key.key == YASL_KEY_C || event->key.key == YASL_KEY_SPACE)
             clear_canvas(app);
     } else if (event->kind == YASL_INPUT_MOUSE) {
         const struct yasl_mouse_event *pointer = &event->mouse;