diff options
| -rw-r--r-- | README.md | 13 | ||||
| -rw-r--r-- | lib/Makefile | 1 | ||||
| -rw-r--r-- | lib/libgfx/Makefile | 1 | ||||
| -rw-r--r-- | lib/libgfx/include/libgfx/draw.h | 11 | ||||
| -rw-r--r-- | lib/libgfx/include/libgfx/gfx.h | 11 | ||||
| -rw-r--r-- | lib/liboda/Makefile | 29 | ||||
| -rw-r--r-- | lib/liboda/include/liboda/oda.h | 89 | ||||
| -rw-r--r-- | lib/liboda/include/liboda/odavar.h | 59 | ||||
| -rw-r--r-- | lib/liboda/include/liboda/types.h | 40 | ||||
| -rw-r--r-- | lib/liboda/src/oda.c | 77 | ||||
| -rw-r--r-- | lib/liboda/src/window.c | 153 | ||||
| -rw-r--r-- | share/docs/kernel/ctlfs.md | 2 | ||||
| -rw-r--r-- | share/docs/lib/liboda.md | 191 |
13 files changed, 661 insertions, 16 deletions
@@ -2,9 +2,9 @@ The Hyra Operating System ========================= Welcome to the Hyra Operating System project! Hyra is an experimental -operating system inspired by BSD and Plan 9 while being entirely written -entirely from scratch. Hyra aims to rethink core fundamentals in modern operating system design -in order to create new and improved architectural ideas. +operating system inspired by BSD and Plan 9 while being entirely written from scratch. +Hyra aims to rethink core fundamentals in modern operating system design in order to +create new and improved architectural ideas. Project Goal: @@ -72,7 +72,12 @@ And more! See ``lib/*`` Documentation: -------------- -Documentation will be in the form of comments throughout the codebase and can also be found in the share/ directory within the project root. +Documentation will be in the form of comments throughout the codebase and can also be found in: + +- ``share/man/*``: Man pages +- ``share/contrib``: Information on contributing +- ``share/docs/kernel``: Kernel documentation +- ``share/docs/lib``: Library documentation Hyra running on bare metal: -------------- diff --git a/lib/Makefile b/lib/Makefile index 4ad104b..fc77815 100644 --- a/lib/Makefile +++ b/lib/Makefile @@ -7,3 +7,4 @@ ARGS = -I$(ROOT)/builddeps LDSCRIPT=$(LDSCRIPT) USRDIR=$(USRDIR) ROOT=$(ROOT) all: make -C libc/ $(ARGS) make -C libgfx/ $(ARGS) + make -C liboda/ $(ARGS) diff --git a/lib/libgfx/Makefile b/lib/libgfx/Makefile index 1f866ac..12fdd9a 100644 --- a/lib/libgfx/Makefile +++ b/lib/libgfx/Makefile @@ -4,7 +4,6 @@ CFILES = $(shell find src/ -name "*.c") OBJ = $(CFILES:.c=.o) all: headers $(OBJ) build/libgfx.a - echo "----------------------------------------" echo $(USRDIR) mv build/libgfx.a $(USRDIR)/lib/ cp -r include/ $(USRDIR)/include/ diff --git a/lib/libgfx/include/libgfx/draw.h b/lib/libgfx/include/libgfx/draw.h index 60d2b24..3bd013a 100644 --- a/lib/libgfx/include/libgfx/draw.h +++ b/lib/libgfx/include/libgfx/draw.h @@ -36,6 +36,17 @@ /* Shape types */ #define SHAPE_SQUARE 0x00000000 +/* Basic color defines */ +#define GFX_BLACK 0x000000 +#define GFX_RED 0xFF0000 +#define GFX_GREEN 0x00FF00 +#define GFX_BLUE 0x0000FF +#define GFX_WHITE 0xFFFFFF +#define GFX_PURPLE 0x800080 +#define GFX_YELLOW 0xFFFF00 +#define GFX_DARK 0x1D2021 +#define GFX_AQUA 0x427B58 + /* * Default shape initializer, something that * works and can be tweaked. The idea of this diff --git a/lib/libgfx/include/libgfx/gfx.h b/lib/libgfx/include/libgfx/gfx.h index 3468571..67a1006 100644 --- a/lib/libgfx/include/libgfx/gfx.h +++ b/lib/libgfx/include/libgfx/gfx.h @@ -48,17 +48,6 @@ typedef uint32_t pixel_t; typedef pixel_t color_t; /* - * Basic color defines - */ -#define GFX_BLACK 0x000000 -#define GFX_RED 0xFF0000 -#define GFX_GREEN 0x00FF00 -#define GFX_BLUE 0x0000FF -#define GFX_WHITE 0xFFFFFF -#define GFX_PURPLE 0x800080 -#define GFX_YELLOW 0xFFFF00 - -/* * Represents cartesian x/y values */ typedef uint32_t cartpos_t; diff --git a/lib/liboda/Makefile b/lib/liboda/Makefile new file mode 100644 index 0000000..5b4022c --- /dev/null +++ b/lib/liboda/Makefile @@ -0,0 +1,29 @@ +CFLAGS = -c -fno-stack-protector -nostdlib -static \ + -Iinclude/ -I$(USRDIR)/include/ +CFILES = $(shell find src/ -name "*.c") +OBJ = $(CFILES:.c=.o) + +all: headers $(OBJ) build/liboda.a + echo $(USRDIR) + mv build/liboda.a $(USRDIR)/lib/ + cp -r include/ $(USRDIR)/include/ + +build/liboda.a: + mkdir -p build/ + ar rcs build/liboda.a $(OBJ) + +%.o: %.c + $(CC) $(CFLAGS) -Iinclude/ $< -o $@ + +.PHONY: headers +headers: + cp -rf include/* $(USRDIR)/include/ + +.PHONY: +build/: + mkdir -p build/ + +.PHONY: clean +clean: + rm -f $(OBJ) + rm -rf build/ diff --git a/lib/liboda/include/liboda/oda.h b/lib/liboda/include/liboda/oda.h new file mode 100644 index 0000000..d807a50 --- /dev/null +++ b/lib/liboda/include/liboda/oda.h @@ -0,0 +1,89 @@ +/* + * Copyright (c) 2023-2025 Ian Marco Moffett and the Osmora Team. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. Neither the name of Hyra nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef LIBODA_ODA_H +#define LIBODA_ODA_H 1 + +#include <sys/queue.h> +#include <stdint.h> +#include <stddef.h> +#include <liboda/types.h> +#include <libgfx/gfx.h> +#include <libgfx/draw.h> + +/* + * ODA representation of a window. + * + * @surface: Window surface descriptor + * @session: Session this window belongs to + */ +struct oda_window { + struct gfx_shape surface; + struct oda_state *session; + TAILQ_ENTRY(oda_window) link; +}; + +/* + * ODA session + * + * @winq: Window queue + * @gctx: Graphics context + * @cookie: State cookie (ODA_COOKIE) + */ +struct oda_state { + TAILQ_HEAD(, oda_window) winq; + struct gfx_ctx gctx; + uint32_t cookie; +}; + +/* + * ODA window attributes. Arguments to be + * passed to oda_window_new() + * + * @session: Current ODA session / state + * @parent: Window parent (NULL for root) + * @pg: Background color (0xRRGGBB) + * @x,y: Window position + * @w,h: Window width [w] and height [h] + */ +struct oda_wattr { + struct oda_state *session; + struct oda_window *parent; + odacolor_t bg; + odapos_t x, y; + odadimm_t w, h; +}; + +int oda_reqwin(struct oda_wattr *params, struct oda_window **res); +int oda_termwin(struct oda_state *state, struct oda_window *win); + +int oda_start_win(struct oda_state *state, struct oda_window *win); +int oda_init(struct oda_state *res); + +#endif /* !LIBODA_ODA_H */ diff --git a/lib/liboda/include/liboda/odavar.h b/lib/liboda/include/liboda/odavar.h new file mode 100644 index 0000000..d2dbe2e --- /dev/null +++ b/lib/liboda/include/liboda/odavar.h @@ -0,0 +1,59 @@ +/* + * Copyright (c) 2023-2025 Ian Marco Moffett and the Osmora Team. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. Neither the name of Hyra nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef LIBODA_ODAVAR_H +#define LIBODA_ODAVAR_H + +#include <sys/param.h> +#include <sys/errno.h> +#include <liboda/oda.h> + +/* + * Default window attributes + */ +#define DEFAULT_WIN_HEIGHT 200 +#define DEFAULT_WIN_WIDTH 150 + +/* + * Verify that ODA structures have been properly + * initialized before usage to prevent undefined + * behaviour. + */ +#define ODA_COOKIE 0xFAFECAD + +/* + * Verify an ODA cookie - internal usage + */ +__always_inline static inline int +oda_cookie_verify(struct oda_state *state) +{ + return (state->cookie == ODA_COOKIE) ? 0 : -EFAULT; +} + +#endif /* !LIBODA_ODAVAR_H */ diff --git a/lib/liboda/include/liboda/types.h b/lib/liboda/include/liboda/types.h new file mode 100644 index 0000000..8b77aa7 --- /dev/null +++ b/lib/liboda/include/liboda/types.h @@ -0,0 +1,40 @@ +/* + * Copyright (c) 2023-2025 Ian Marco Moffett and the Osmora Team. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. Neither the name of Hyra nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef LIBODA_TYPE_H +#define LIBODA_TYPE_H + +#include <stdint.h> + +typedef uint32_t odapos_t; /* X/Y positions */ +typedef uint32_t odapix_t; /* RGB pixel */ +typedef odapix_t odacolor_t; /* RGB color */ +typedef uint32_t odadimm_t; /* Dimensions */ + +#endif /* !LIBODA_TYPE_H */ diff --git a/lib/liboda/src/oda.c b/lib/liboda/src/oda.c new file mode 100644 index 0000000..0eef523 --- /dev/null +++ b/lib/liboda/src/oda.c @@ -0,0 +1,77 @@ +/* + * Copyright (c) 2023-2025 Ian Marco Moffett and the Osmora Team. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. Neither the name of Hyra nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/errno.h> +#include <stdio.h> +#include <libgfx/gfx.h> +#include <liboda/oda.h> +#include <liboda/odavar.h> + +#define oda_log(fmt, ...) printf("oda: " fmt, ##__VA_ARGS__) + +/* + * Initialize the OSMORA Display Architecture + * (ODA) library. + * + * @res: Initialized ODA state result + * + * Returns 0 on success, otherwise a less than + * zero value. + */ +int +oda_init(struct oda_state *res) +{ + int error; + + /* Ensure the argument is valid */ + if (res == NULL) { + return -EINVAL; + } + + /* + * If this state has already been initialized, + * assume programmer error / undefined behaviour + * and let them know. + */ + if (oda_cookie_verify(res) == 0) { + oda_log("oda_init: 'res' already initialized\n"); + return -EBUSY; + } + + /* Initialize the graphics context */ + error = gfx_init(&res->gctx); + if (error != 0) { + oda_log("oda_init: could not init graphics context\n"); + return error; + } + + TAILQ_INIT(&res->winq); + res->cookie = ODA_COOKIE; + return 0; +} diff --git a/lib/liboda/src/window.c b/lib/liboda/src/window.c new file mode 100644 index 0000000..876f89e --- /dev/null +++ b/lib/liboda/src/window.c @@ -0,0 +1,153 @@ +/* + * Copyright (c) 2023-2025 Ian Marco Moffett and the Osmora Team. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. Neither the name of Hyra nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/errno.h> +#include <stdlib.h> +#include <string.h> +#include <liboda/oda.h> +#include <liboda/odavar.h> +#include <liboda/types.h> +#include <libgfx/gfx.h> + +/* + * Request a window from the OSMORA Display + * Architecture (ODA). + * + * @params: Arguments + * @res: Resulting pointer for new window + * + * Returns 0 on success, otherwise a less than + * zero value. + */ +int +oda_reqwin(struct oda_wattr *params, struct oda_window **res) +{ + struct oda_window *wp; + struct gfx_shape *surf; + struct oda_state *session; + int error; + + if (params == NULL || res == NULL) { + return -EINVAL; + } + + /* Try to grab the current session */ + if ((session = params->session) == NULL) { + return -EIO; + } + + /* Verify that cookie! */ + if ((error = oda_cookie_verify(session)) != 0) { + return error; + } + + /* Allocate a new window */ + wp = malloc(sizeof(*wp)); + if (wp == NULL) { + return -ENOMEM; + } + + /* Initialize the window */ + memset(wp, 0, sizeof(*wp)); + wp->session = session; + TAILQ_INSERT_TAIL(&session->winq, wp, link); + + /* Fix up width/height params */ + if (params->w == 0) + params->w = DEFAULT_WIN_WIDTH; + if (params->h == 0) + params->h = DEFAULT_WIN_HEIGHT; + + /* Initialize the window surface */ + surf = &wp->surface; + surf->color = params->bg; + surf->x = params->x; + surf->y = params->y; + surf->width = params->w; + surf->height = params->h; + surf->type = SHAPE_SQUARE; + *res = wp; + return 0; +} + +/* + * Register a window into the current ODA state. + * Everytime a compositor requests a window, we + * must keep track of it. + * + * @state: ODA state pointer + * @win: Pointer of window to register + */ +int +oda_start_win(struct oda_state *state, struct oda_window *win) +{ + int error; + + if (state == NULL || win == NULL) { + return -EINVAL; + } + + /* Make sure the state is valid */ + if ((error = oda_cookie_verify(state)) != 0) { + return error; + } + + gfx_draw_shape(&state->gctx, &win->surface); + return 0; +} + +/* + * Terminate a running window + * + * @state: ODA state pointer + * @win: Win pointer + * + * Returns 0 on success, otherwise a less than + * zero value. + * + * TODO: Cleanup screen + */ +int +oda_termwin(struct oda_state *state, struct oda_window *win) +{ + int error; + + if (state == NULL || win == NULL) { + return -EINVAL; + } + + /* Validate the cookie */ + if ((error = oda_cookie_verify(state)) != 0) { + return error; + } + + TAILQ_REMOVE(&state->winq, win, link); + free(win); + return 0; +} diff --git a/share/docs/kernel/ctlfs.md b/share/docs/kernel/ctlfs.md index d549a81..3087f60 100644 --- a/share/docs/kernel/ctlfs.md +++ b/share/docs/kernel/ctlfs.md @@ -1,5 +1,7 @@ # The Hyra control filesystem (ctlfs) +Written by Ian M. Moffett + ## Rationale Historically, Operating Systems of the Unix family typically relied diff --git a/share/docs/lib/liboda.md b/share/docs/lib/liboda.md new file mode 100644 index 0000000..f526ca9 --- /dev/null +++ b/share/docs/lib/liboda.md @@ -0,0 +1,191 @@ +# The OSMORA Display Architecture (ODA) + +Written by Ian M. Moffett + +## Introduction + +The OSMORA Display Architecture (ODA) is a protocol describing how +a compositor should create and manage graphical windows. A graphical +session in Hyra consists of a compositor, window management system and +management of user input. + +There are many existing display architectures out there. Take for instace, the X11 +protocol. X11 for example, has the concept of an "X server" in which window managers +or certain graphical programs would connect to as a means of performing interprocess +communication (IPC). The idea is that X will service graphics related requests from +the window manager or compositor. + +While this works just fine, the highly centralized nature of X11 or similar protocols +may complicate the flexibility of the graphics stack. On the other hand with ODA, a +compositor links with the ODA library and becomes the server for window managers running +on the system. The idea of ODA is to minimize complexity while preserving flexibility. + +Additionally, the compositor should provide its own API for use by window management +software. + +## Scope + +This document serves to describe common OSMORA Display Architecture (ODA) concepts +as well as providing basic example C sources showcasing how compositors and window +managers may interface with the described APIs for various needs. + +## Terminology + +### OSMORA Display Architecture (ODA): + +OSMORA protocol defining common interfaces for C2W and +W2C interactions. + +### Compositor to window (C2W): + +Describes the direction of communication originating from +a compositor and directed towards a specific window: + +``COMPOSITOR -> WINDOW`` + +### Window to compositor (W2C): + +Describes the direction of communication originating from +a specific window to a compositor running on the system: + +``WINDOW -> COMPOSITOR`` + +## Architecture + +``` ++-------------+ +| LIBGFX | ++-------------+ + ^ + | linked with libgfx + V ++-------------+ +| COMPOSITOR | ++-------------+ <---+ signal + | | | | + | | | | c2w: <winop: e.g., close> + | | | | w2c: <winop to accept: e.g., close> + WIN WIN WIN <---+ +``` + +### C2W signal flow: + +``` +-- CLOSE SIGNAL EXAMPLE -- + +WINDOW RECEIVES CLOSE SIGNAL + | + ECHO BACK TO COMPOSITOR + | + YES ---+--- NO + | | + | V + | nothing happens + | + V + window is destroyed by compositor +``` + +## Libgfx + +The Hyra userspace includes ``libgfx`` which is a low-level graphics library aimed +to facilitate drawing on the screen and performing various graphical operations while +decoupling from the concept of compositors, windows and the ODA as a whole. In other words, +libgfx has no knowledge of anything outside of the framebuffer and itself. + +The following is an example of how one may draw a yellow square at +x/y (30,0): + +```c +#include <libgfx/gfx.h> /* Common routines/defs */ +#include <libgfx/draw.h> /* Drawing related routines/defs */ + +int +main(void) +{ + struct gfx_ctx ctx; + struct gfx_shape sh = GFX_SHAPE_DEFAULT; + int error; + + /* Set the x/y and color */ + sh.x = 30; + sh.y = 0; + sh.color = GFX_YELLOW + + error = gfx_init(&ctx); + if (error < 0) { + printf("gfx_init returned %d\n", error); + return error; + } + + /* Draw the square and cleanup */ + gfx_draw_shape(&ctx, &sh); + gfx_cleanup(&ctx); + return 0; +} +``` + +## Liboda + +The Hyra userspace includes the ``liboda`` library which includes various +interfaces conforming to the OSMORA Display Architecture (ODA). + +### Linking a compositor with liboda + +In order for an ODA compliant compositor to reference library +symbols for ``liboda``, it should use the following linker flags: + +``... -loda -logfx`` + +### ODA Session + +For the ODA library to keep track of state, it relies on an ``oda_state`` +structure defined in ``liboda/oda.h``. Additionally, in order for any ODA +library calls to be made, the compositor must initialize the library with +``oda_init()`` like in the following example: + +``` +#include <liboda/oda.h> + +struct oda_state state; +int error; + +/* Returns 0 on success */ +error = oda_init(&state); +... +``` + +Upon failure of ``oda_init()`` a negative POSIX errno value +is returned (see ``sys/errno.h``). + +### Using liboda to request windows + +A compositor may request windows from the ODA by using +``oda_reqwin()`` like in the following example: + +``` +#include <liboda/oda.h> + +... +struct oda_wattr wattr; +struct oda_state state; + +... + +wattr.session = &state; +wattr.parent = NULL; +wattr.bg = GFX_YELLOW; +wattr.x = 200; +wattr.y = 150; +wattr.w = 120; +wattr.h = 300; + +/* Returns 0 on success */ +error = oda_reqwin(&wattr, &win); +``` + +Arguments passed to ``oda_reqwin()`` are first stored in a ``struct oda_wattr`` +structure to minimize the number of parameters used in the function signature. + +Upon failure of ``oda_reqwin()`` a negative POSIX errno value +is returned (see ``sys/errno.h``). |