{"id":9987,"date":"2022-06-21T09:10:37","date_gmt":"2022-06-21T09:10:37","guid":{"rendered":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/documentation\/rdk_video_documentation\/components\/open-sourced_components\/westeros\/"},"modified":"2026-09-22T06:12:22","modified_gmt":"2026-09-22T06:12:22","slug":"westeros","status":"publish","type":"page","link":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/","title":{"rendered":"Westeros"},"content":{"rendered":"\n

Westeros is a lightweight Wayland compositor library that enables applications to create one or more Wayland displays. It is designed to be compatible with applications built for standard Wayland compositors and is structured as a library rather than a standalone application, allowing it to be embedded inside a host process. It supports three compositor modes: a normal<\/strong> compositor that renders its composited output directly to the screen, a nested<\/strong> compositor that connects to another compositor as a client and renders onto a surface of that parent compositor, and an embedded<\/strong> compositor whose composited output is driven by the hosting application through explicit calls. This flexibility allows Westeros to act as the top-level display server on a device, as an intermediary layer in a compositor chain, or as an off-screen compositor integrated into an application’s rendering pipeline.<\/p>\n\n\n\n

At the device level, Westeros provides a Wayland display endpoint that UI frameworks, media players, and other application runtimes connect to as Wayland clients. At the module level, it exposes a C API for creating, configuring, and starting compositor instances, a pluggable renderer interface that allows vendor-specific rendering backends to be loaded at runtime, and a set of Wayland protocol extensions \u2014 Simple Shell, VPC, linux-dmabuf, and explicit sync \u2014 that provide surface management and video path control beyond the base Wayland protocol.<\/p>\n\n\n\n

flowchart LR\n\nclassDef Apps stroke:#00B9F1,fill:#E6F7FD,stroke-width:2px\nclassDef RDKMW stroke:#75D701,fill:#F1FFE6,stroke-width:2px\nclassDef VL stroke:#808080,fill:#F2F2F2,stroke-width:2px\n\n    subgraph Apps[\"Apps and Runtimes\"]\n        RDKUI[\"UI\"]\n        FBApps[\"Firebolt Apps\"]\n        WPE_RT[\"WPE Runtime\"]\n    end\n\n    subgraph RDKMW_SUB[\"RDK Core Middleware\"]\n        AM[\"App Manager\"]\n        Rialto[\"Rialto\"]\n        Westeros[\"Westeros Wayland Compositor\"]\n        Thunder[\"WPEFramework Thunder\"]\n    end\n\n    subgraph VL_SUB[\"Vendor Layer\"]\n        SOCHAL[\"westeros-soc SOC Render HAL\"]\n        BSP[\"BSP\"]\n        DRM[\"DRM EGL Libraries\"]\n    end\n\n    RDKUI -->|Wayland Protocol| Westeros\n    FBApps -->|Wayland Protocol| Westeros\n    WPE_RT -->|Wayland Protocol| Westeros\n    Westeros -->|Renderer Module API| SOCHAL<\/pre><\/div>\n\n\n\n
Key Features & Responsibilities:<\/strong><\/p>\n\n\n\n
    \n
  • Multiple Compositor Modes<\/strong>: Westeros operates as a normal (top-level), nested, or embedded compositor. A nested compositor connects to a parent Wayland display and forwards its composited output as a client surface; an embedded compositor exposes its scene only when the host application triggers composition explicitly via WstCompositorComposeEmbedded<\/code>.<\/li>\n\n\n\n
  • Pluggable Renderer Interface<\/strong>: The rendering backend is loaded at runtime from a shared library specified by WstCompositorSetRendererModule<\/code>. Renderer modules implement a defined function table (WstRenderer<\/code>) covering surface create\/destroy, buffer commit, geometry, opacity, z-order, crop, and DMA-buf operations.<\/li>\n\n\n\n
  • Surface and Shell Protocol Support<\/strong>: Westeros implements wl_compositor<\/code>, wl_shell<\/code>, and one build-selected xdg-shell<\/code> variant (v4, v5, or stable) server-side. Each client surface is tracked as a WstSurface<\/code> with full position, size, opacity, z-order, and popup relationship state.<\/li>\n\n\n\n
  • Input Routing<\/strong>: Keyboard, pointer, and touch input is injected via the compositor API (WstCompositorKeyEvent<\/code>, WstCompositorPointerMoveEvent<\/code>, WstCompositorPointerButtonEvent<\/code>, WstCompositorTouchEvent<\/code>) and dispatched through standard Wayland seat protocols to the focused surface. Keyboard layout is managed via libxkbcommon with configurable key repeat delay and rate.<\/li>\n\n\n\n
  • Video Path Control (VPC)<\/strong>: The proprietary vpc<\/code> Wayland protocol extension allows a video surface to declare whether its content follows a hardware or graphics path and communicates position and scale transforms to the compositor chain, enabling hole-punch and hardware video overlay positioning.<\/li>\n\n\n\n
  • Wayland Protocol Extensions<\/strong>: Optionally compiled-in extensions include wl_sb<\/code> (shared buffer), zwp_linux_dmabuf_v1<\/code> (DMA-buf import), linux_explicit_synchronization_unstable_v1<\/code> (acquire\/release fence synchronization), and wl_simple_shell<\/code> for privileged surface management.<\/li>\n\n\n\n
  • Extensible Module System<\/strong>: Additional Wayland protocols or functionality can be added at runtime by loading external shared libraries that provide moduleInit<\/code> and moduleTerm<\/code> entry points, registered via WstCompositorAddModule<\/code>.<\/li>\n\n\n\n
  • Repeater Mode<\/strong>: When supported by the platform’s Wayland-EGL path, a repeating nested compositor forwards client surface buffers directly to the parent compositor without intermediate composition; otherwise Westeros falls back to nested composition with the GL renderer.<\/li>\n\n\n\n
  • Virtual Embedded Compositors<\/strong>: Multiple virtual embedded compositor instances can be created from a single master embedded compositor via WstCompositorCreateVirtualEmbedded<\/code>, allowing independent sub-scene management within one process.<\/li>\n<\/ul>\n\n\n\n
    \n\n\n\n
    Design<\/h2>\n\n\n\n
    Westeros is designed around a library model where the compositor runs inside the host process. The compositor context (WstContext<\/code>) holds all shared state and runs a dedicated compositor thread that owns the Wayland display event loop, client connections, and frame generation. The public WstCompositor<\/code> handle is the per-instance API object and decouples the calling thread from the compositor thread, with a 64-entry event queue (WstEvent<\/code>) bridging input events from the application thread to the compositor thread. A recursive pthread mutex (ctx->mutex<\/code>) serializes access to shared context state between the caller and the compositor thread.<\/p>\n\n\n\n
    The three compositor modes \u2014 normal, nested, and embedded \u2014 are controlled by flags set before WstCompositorStart<\/code> is called. In nested mode, a WstNestedConnection<\/code> is established on a separate thread to maintain the connection to the parent Wayland display, receiving output geometry, keyboard map, and VPC events from the parent and forwarding them into the local compositor event flow. In embedded mode, composition is triggered only when the hosting application calls WstCompositorComposeEmbedded<\/code>, and both that call and WstCompositorStart<\/code> must be issued from the same thread. Normal mode drives composition from a timer event source on the compositor thread at the configured frame rate.<\/p>\n\n\n\n
    Rendering is fully decoupled through the WstRenderer<\/code> interface: the compositor calls renderer_init<\/code> in the loaded module to populate a function table, then calls surfaceCreate<\/code>, surfaceCommit<\/code>, updateScene<\/code>, and related methods for each frame. This separation means the compositor core has no dependency on any specific GPU API; EGL and GLES2 are engaged only when a GL-based renderer module is loaded. Buffer sharing between clients and the renderer is handled through wl_shm<\/code>, wl_sb<\/code>, zwp_linux_dmabuf_v1<\/code>, or EGL Wayland buffer extensions, depending on which protocols are enabled at build time.<\/p>\n\n\n\n
    Northbound interaction with hosted clients is via the Wayland socket protocol: clients connect, bind globals, create surfaces, attach buffers, and commit. The hosting application also controls embedded instances through the C API, while southbound interaction is through the renderer module’s function table.<\/p>\n\n\n\n
    For non-nested starts, the keyboard map is initialized from libxkbcommon using the evdev rule set and the us layout by default; nested instances receive the parent compositor’s keymap.<\/p>\n\n\n\n
    graph TD\n    subgraph WesterosProcess[\"Westeros Process\"]\n        subgraph PublicAPI[\"Public API Layer\"]\n            WstComp[\"WstCompositor API Handle\"]\n        end\n\n        subgraph CoreContext[\"Compositor Context WstContext\"]\n            CompThread[\"Compositor Thread wstCompositorThread\"]\n            EventQ[\"Event Queue 64 entries\"]\n            SurfaceMap[\"Surface Map surfaceId to WstSurface\"]\n            Seat[\"WstSeat keyboard pointer touch\"]\n            Output[\"WstOutput geometry and mode\"]\n            ShellGlobals[\"Shell Globals wl_shell xdg_shell wl_simple_shell\"]\n        end\n\n        subgraph RendMod[\"Renderer Module dlopen\"]\n            RendGL[\"libwesteros_render_gl or libwesteros_render_embedded\"]\n        end\n\n        subgraph NConn[\"Nested Connection\"]\n            NCThread[\"Nested Connection Thread\"]\n        end\n    end\n\n    subgraph VendorLayer[\"Vendor Layer\"]\n        SOC[\"westeros-soc DRM EGL\"]\n    end\n\n    WstComp -->|enqueue input events| EventQ\n    EventQ -->|drain and dispatch| CompThread\n    CompThread -->|surface commit and compose| RendGL\n    NCThread -->|output keyboard VPC callbacks| CompThread\n    RendGL -->|EGL GLES2 DMA-buf| SOC\n    NCThread -->|nested wl events| CompThread<\/pre><\/div>\n\n\n\n
    Threading Model<\/h4>\n\n\n\n
      \n
    • Threading Architecture<\/strong>: Multi-threaded<\/li>\n\n\n\n
    • Main \/ Caller Thread<\/strong>: Invokes WstCompositorCreate<\/code>, WstCompositorSet*<\/code>, WstCompositorStart<\/code>, and input injection APIs. Posts events to the per-compositor event queue.<\/li>\n\n\n\n
    • Worker Threads<\/strong>:<\/li>\n\n\n\n
    • Compositor thread<\/em> (wstCompositorThread<\/code>): Runs the wl_display<\/code> event loop, accepts client connections, dispatches protocol requests, schedules repaints, drives frame composition at the configured frame rate, and manages surface lifecycle.<\/li>\n\n\n\n
    • Nested connection thread<\/em>: Active in nested, repeater, or embedded VPC-bridge mode. Maintains the Wayland client connection to the parent compositor, receives output geometry, keyboard map, and VPC notifications, and posts them into the compositor context.<\/li>\n\n\n\n
    • Synchronization<\/strong>: A recursive pthread mutex (ctx->mutex<\/code>) protects the compositor context and surface\/client maps. A mutex and condition variable pair (ncStartedMutex<\/code>, ncStartedCond<\/code>) synchronizes the start of the nested connection thread with the compositor thread startup. The master embedded compositor uses a separate global mutex (g_mutexMasterEmbedded<\/code>).<\/li>\n\n\n\n
    • Async \/ Event Dispatch<\/strong>: Input injection APIs append to the fixed 64-entry WstCompositor::eventQueue<\/code>, indexed by eventIndex<\/code>; wstCompositorProcessEvents<\/code> drains the batch and resets the index. It dispatches each event type to the matching handler (wstProcessKeyEvent<\/code>, wstProcessPointerMoveEvent<\/code>, wstProcessTouchDownEvent<\/code>, etc.).<\/li>\n<\/ul>\n\n\n\n
      Prerequisites and Dependencies<\/h3>\n\n\n\n
      Platform and Integration Requirements<\/h4>\n\n\n\n
        \n
      • Build Dependencies<\/strong>: wayland-client<\/code> (\u22651.6.0), wayland-server<\/code> (\u22651.6.0), wayland-egl<\/code>, libxkbcommon<\/code> (\u22650.4), EGL<\/code>, GLESv2<\/code>, glib-2.0<\/code> (\u22652.22.5), gstreamer-1.0<\/code> (\u22651.0), virtual\/westeros-soc<\/code> (SOC render module), westeros-simplebuffer<\/code>, westeros-simpleshell<\/code>, wayland-native<\/code> (for protocol scanner at build time). wayland-protocols<\/code> is required when the explicit-sync<\/code> PACKAGECONFIG is enabled; libdrm<\/code> headers are required when incldbprotocol<\/code> is enabled.<\/li>\n\n\n\n
      • Device Services \/ HAL<\/strong>: Vendor-specific rendering is provided by the virtual\/westeros-soc<\/code> recipe, resolved at build time to a platform renderer module. The module exports a renderer_init<\/code> symbol and populates the WstRenderer<\/code> function table covering renderTerm<\/code>, updateScene<\/code>, surfaceCreate<\/code>, surfaceDestroy<\/code>, surfaceCommit<\/code>, surfaceSetVisible<\/code>, surfaceGetVisible<\/code>, surfaceSetGeometry<\/code>, surfaceGetGeometry<\/code>, surfaceSetOpacity<\/code>, surfaceGetOpacity<\/code>, surfaceSetZOrder<\/code>, surfaceGetZOrder<\/code>, surfaceSetCrop<\/code>, and holePunch<\/code>.<\/li>\n\n\n\n
      • Systemd Services<\/strong>: The westeros.service<\/code> unit sources \/etc\/default\/westeros-env<\/code> and executes \/usr\/bin\/westeros-init<\/code>. The init script waits up to 60 seconds for XDG_RUNTIME_DIR<\/code> to be mounted before launching the compositor.<\/li>\n\n\n\n
      • Configuration Files<\/strong>: Runtime configuration is supplied through \/etc\/default\/westeros-env<\/code>, sourced by the systemd service unit.<\/li>\n\n\n\n
      • Startup Order<\/strong>: RequiresMountsFor=\/run<\/code> in westeros.service<\/code>; WantedBy=multi-user.target<\/code>.<\/li>\n<\/ul>\n\n\n\n
        \n\n\n\n
        Component State Flow<\/h3>\n\n\n\n
        Initialization to Active State<\/h4>\n\n\n\n
        The compositor transitions through the following states during its lifecycle: Uninitialized<\/strong> (before WstCompositorCreate<\/code>) \u2192 Configured<\/strong> (WstCompositorSet*<\/code> calls establish display name, renderer module, frame rate, and mode flags) \u2192 Starting<\/strong> (WstCompositorStart<\/code> spawns the compositor thread) \u2192 Ready<\/strong> (the compositor thread has created the Wayland display, seat, output, and shell globals; embedded mode initializes its renderer immediately after this signal in WstCompositorStart<\/code>) \u2192 Active<\/strong> (the compositor thread runs the event loop, accepting client connections and generating frames) \u2192 Shutdown<\/strong> (WstCompositorStop<\/code> signals the compositor thread to exit, renderer and seat resources are released).<\/p>\n\n\n\n
        sequenceDiagram\n    participant App as Host Application\n    participant Comp as WstCompositor API\n    participant CThread as Compositor Thread\n    participant Renderer as Renderer Module\n    participant XKB as libxkbcommon\n\n    App->>Comp: WstCompositorCreate()\n    App->>Comp: WstCompositorSetRendererModule()\n    App->>Comp: WstCompositorSetDisplayName()\n    App->>Comp: WstCompositorSetFrameRate()\n    App->>Comp: WstCompositorStart()\n    Comp->>CThread: pthread_create wstCompositorThread\n    CThread->>XKB: xkb_context_new and xkb_keymap_new_from_names\n    XKB-->>CThread: keymap ready\n    CThread->>Renderer: dlopen and renderer_init\n    Renderer-->>CThread: WstRenderer function table populated\n    CThread->>CThread: wl_display_create and register globals\n    CThread->>CThread: wstSeatInit wstOutputInit wstShmInit\n    CThread-->>Comp: compositorReady = true\n    Comp-->>App: WstCompositorStart returns true\n\n    loop Frame Loop\n        CThread->>CThread: wl_display_flush_clients\n        CThread->>Renderer: updateScene\n    end\n\n    App->>Comp: WstCompositorStop()\n    CThread->>Renderer: renderTerm\n    CThread->>CThread: wstSeatTerm wstOutputTerm\n    CThread-->>Comp: thread exits<\/pre><\/div>\n\n\n\n
        Runtime State Changes<\/h4>\n\n\n\n
        State Change Triggers:<\/strong><\/p>\n\n\n\n
          \n
        • Output Size Change<\/strong>: WstCompositorSetOutputSize<\/code> or WstCompositorResolutionChangeEnd<\/code> set outputSizeChanged<\/code> flags; the compositor thread calls wstOutputChangeSize<\/code> on its next iteration, updating all clients with a new wl_output.mode<\/code> event.<\/li>\n\n\n\n
        • Nested Connection Loss<\/strong>: When the nested connection thread detects that the parent compositor has disconnected, it terminates the local Wayland display and invokes the configured termination callback; the compositor thread then exits its event loop and releases resources.<\/li>\n\n\n\n
        • First Frame Notification<\/strong>: During embedded composition, after a non-hidden scene containing a client’s committed buffer is composed, clientStatusCB<\/code> is invoked with WstClient_firstFrame<\/code> once for that client PID.<\/li>\n<\/ul>\n\n\n\n
          Context Switching Scenarios:<\/strong><\/p>\n\n\n\n
            \n
          • When operating as a nested compositor, output geometry or keyboard map changes from the parent compositor propagate into the local compositor context and are forwarded to all connected clients.<\/li>\n\n\n\n
          • In embedded mode, the host application controls composition timing by calling WstCompositorComposeEmbedded<\/code> directly.<\/li>\n<\/ul>\n\n\n\n
            \n\n\n\n
            Call Flows<\/h3>\n\n\n\n
            Initialization Call Flow<\/h4>\n\n\n\n
            sequenceDiagram\n    participant App as Host Application\n    participant API as WstCompositor API\n    participant CThread as Compositor Thread\n    participant Renderer as Renderer Module\n    participant WlDisplay as wl_display\n\n    App->>API: WstCompositorCreate()\n    App->>API: WstCompositorSet display renderer framerate mode\n    App->>API: WstCompositorStart()\n    API->>CThread: pthread_create\n    CThread->>WlDisplay: wl_display_create()\n    CThread->>WlDisplay: register globals wl_compositor wl_shm wl_seat wl_output xdg_shell wl_simple_shell vpc\n    CThread->>Renderer: dlopen rendererModule and renderer_init\n    Renderer-->>CThread: WstRenderer function table\n    CThread->>CThread: wstSeatInit wstOutputInit wstShmInit\n    CThread-->>API: compositorReady = true\n    API-->>App: WstCompositorStart returns true<\/pre><\/div>\n\n\n\n
            Request Processing Call Flow<\/h4>\n\n\n\n
            Surface buffer rendering is the primary runtime operation. A Wayland client attaches a buffer to its surface and issues a commit. The compositor thread receives the commit, passes the buffer to the renderer module for upload or import, schedules a repaint, and on the next frame tick calls the renderer’s updateScene<\/code> to produce the composited output.<\/p>\n\n\n\n
            sequenceDiagram\n    participant WlClient as Wayland Client\n    participant CThread as Compositor Thread\n    participant Renderer as Renderer Module\n    participant SOC as Vendor SOC Layer\n\n    WlClient->>CThread: wl_surface.attach buffer\n    WlClient->>CThread: wl_surface.commit\n    CThread->>CThread: wstISurfaceCommit update WstSurface state\n    CThread->>Renderer: surfaceCommit surface bufferResource\n    Renderer->>SOC: import or upload buffer via EGL or DMA-buf\n    SOC-->>Renderer: texture or buffer handle\n    CThread->>CThread: wstCompositorScheduleRepaint\n    Note over CThread: next frame tick\n    CThread->>Renderer: updateScene\n    Renderer->>SOC: draw surfaces via GLES2 or HW overlay\n    CThread->>WlClient: frame callback done<\/pre><\/div>\n\n\n\n
            \n\n\n\n
            Internal Modules<\/h2>\n\n\n\n
            Module \/ Class<\/th>Description<\/th>Key Files<\/th><\/tr><\/thead>
            WstCompositor<\/code><\/td>Public API handle. Holds per-instance output dimensions, keyboard\/pointer\/touch objects, client status callbacks, and the 64-entry event queue. Each virtual embedded instance has its own WstCompositor<\/code> sharing a single WstContext<\/code>.<\/td>westeros-compositor.cpp<\/code>, westeros-compositor.h<\/code><\/td><\/tr>
            WstContext<\/code><\/td>Internal compositor context. Owns the wl_display<\/code>, compositor thread, renderer module, seat, output, surface maps, nested connection, and all Wayland global objects. One WstContext<\/code> per non-virtual compositor instance.<\/td>westeros-compositor.cpp<\/code><\/td><\/tr>
            WstRenderer<\/code><\/td>Pluggable rendering interface. Loaded at runtime via dlopen<\/code>; the module exports renderer_init<\/code> to populate a function table of surface and scene operations. Two built-in modules are provided: a GLES2 GL renderer and an embedded renderer.<\/td>westeros-render.h<\/code>, westeros-render-gl.cpp<\/code>, westeros-render-embedded.cpp<\/code><\/td><\/tr>
            WstNestedConnection<\/code><\/td>Manages the Wayland client connection to a parent compositor in nested or repeater mode. Runs on a dedicated thread. Receives output, keyboard, and VPC events from the parent and delivers them via callbacks into the compositor context.<\/td>westeros-nested.h<\/code>, westeros-nested.cpp<\/code><\/td><\/tr>
            WstSurface<\/code><\/td>Per-surface state: position, size, opacity, z-order, attached buffer resource, frame callback list, and explicit-sync fences. Maintains a reference to its WstRenderSurface<\/code> within the renderer and to any associated WstVpcSurface<\/code>.<\/td>westeros-compositor.cpp<\/code><\/td><\/tr>
            WstSeat \/ WstKeyboard \/ WstPointer \/ WstTouch<\/code><\/td>Input seat abstraction. Tracks focused surfaces, current keyboard modifiers via libxkbcommon xkb_state<\/code>, and pointer position. Dispatches Wayland seat events to client resources.<\/td>westeros-compositor.cpp<\/code><\/td><\/tr>
            WstSimpleShell<\/code><\/td>Server implementation of the wl_simple_shell<\/code> protocol. Allows privileged clients to set surface name, visibility, geometry, opacity, z-order, scale, and focus by surface ID, and to receive creation\/destruction broadcast notifications.<\/td>simpleshell\/westeros-simpleshell.cpp<\/code>, simpleshell\/westeros-simpleshell.h<\/code><\/td><\/tr>
            WstVpcSurface<\/code><\/td>Tracks the video path control state for a surface (hardware path vs. graphics path) and the position\/scale transform communicated to the compositor chain via the vpc<\/code> protocol.<\/td>westeros-compositor.cpp<\/code><\/td><\/tr>
            WstLinuxDmabuf<\/code><\/td>Protocol module implementing zwp_linux_dmabuf_v1<\/code>. Handles multi-plane DMA-buf buffer import with format and modifier negotiation between client and renderer.<\/td>linux-dmabuf\/westeros-linux-dmabuf.cpp<\/code>, linux-dmabuf\/westeros-linux-dmabuf.h<\/code><\/td><\/tr>
            WstLinuxExpSync<\/code><\/td>Protocol module implementing linux_explicit_synchronization_unstable_v1<\/code>. Manages per-surface acquire fence descriptors and buffer release fence signalling between client and renderer.<\/td>linux-expsync\/westeros-linux-expsync.cpp<\/code>, linux-expsync\/westeros-linux-expsync.h<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
            \n\n\n\n
            Component Interactions<\/h2>\n\n\n\n
            Westeros operates as a self-contained Wayland display server. Northbound communication is entirely via the Wayland socket protocol; southbound communication is via the renderer module’s function table.<\/p>\n\n\n\n
            Interaction Matrix<\/h3>\n\n\n\n
            Target Component \/ Layer<\/th>Interaction Purpose<\/th>Key APIs \/ Topics<\/th><\/tr><\/thead>
            Wayland Clients<\/strong><\/td><\/td><\/td><\/tr>
            UI \/ App Runtimes<\/td>Surface creation, buffer submission, input reception<\/td>wl_compositor<\/code>, wl_surface<\/code>, wl_seat<\/code>, xdg_shell<\/code>, wl_simple_shell<\/code>, vpc<\/code><\/td><\/tr>
            Media \/ Video Clients<\/td>Video path and position negotiation<\/td>vpc_surface.set_geometry<\/code>, vpc_surface.video_path_change<\/code><\/td><\/tr>
            Renderer Module \/ HAL<\/strong><\/td><\/td><\/td><\/tr>
            virtual\/westeros-soc<\/code> renderer<\/td>Compositing surfaces to display output<\/td>renderer_init()<\/code>, surfaceCommit()<\/code>, updateScene()<\/code>, surfaceSetGeometry()<\/code>, surfaceSetZOrder()<\/code>, holePunch()<\/code><\/td><\/tr>
            EGL \/ GLES2 \/ DMA-buf<\/td>GPU buffer import and rendering<\/td>eglBindWaylandDisplayWL<\/code>, eglQueryWaylandBufferWL<\/code>, WstLDBBufferGet*<\/code><\/td><\/tr>
            System<\/strong><\/td><\/td><\/td><\/tr>
            libxkbcommon<\/td>Keyboard layout and modifier state management<\/td>xkb_context_new<\/code>, xkb_keymap_new_from_names<\/code>, xkb_state_new<\/code>, xkb_state_update_mask<\/code><\/td><\/tr>
            Wayland display socket<\/td>Inter-process communication with compositor clients<\/td>wl_display_create<\/code>, wl_display_add_socket<\/code>, wl_display_run<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
            Events Published<\/h3>\n\n\n\n
            Event Name<\/th>Wayland Topic<\/th>Trigger Condition<\/th>Subscriber<\/th><\/tr><\/thead>
            output.mode<\/code><\/td>wl_output<\/code><\/td>Output size changes via WstCompositorResolutionChangeEnd<\/code><\/td>All connected Wayland clients<\/td><\/tr>
            keyboard.keymap<\/code><\/td>wl_keyboard<\/code><\/td>Compositor start or nested keymap update from parent<\/td>Clients with keyboard focus<\/td><\/tr>
            keyboard.key<\/code> \/ keyboard.modifiers<\/code><\/td>wl_keyboard<\/code><\/td>Key event injected via WstCompositorKeyEvent<\/code><\/td>Client with keyboard focus<\/td><\/tr>
            pointer.motion<\/code> \/ pointer.button<\/code><\/td>wl_pointer<\/code><\/td>Pointer event injected via WstCompositorPointerMoveEvent<\/code> \/ WstCompositorPointerButtonEvent<\/code><\/td>Client under pointer<\/td><\/tr>
            touch.down<\/code> \/ touch.up<\/code> \/ touch.motion<\/code><\/td>wl_touch<\/code><\/td>Touch event injected via WstCompositorTouchEvent<\/code><\/td>Client with touch focus<\/td><\/tr>
            shell_surface.created<\/code> \/ shell_surface.destroyed<\/code><\/td>wl_simple_shell<\/code><\/td>Surface created or destroyed on the display<\/td>All wl_simple_shell<\/code> bound clients<\/td><\/tr>
            vpc_surface.video_path_change<\/code><\/td>vpc<\/code><\/td>Video surface changes path via wstDefaultNestedVpcVideoPathChange<\/code><\/td>VPC-bound client surfaces<\/td><\/tr>
            frame<\/code> callback<\/td>wl_callback<\/code><\/td>Frame composition completed<\/td>Wayland clients that requested frame callback<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
            IPC Flow Patterns<\/h3>\n\n\n\n
            Primary Surface Commit Flow:<\/strong><\/p>\n\n\n\n
            Clients communicate with Westeros over the Wayland socket. Westeros validates the buffer resource type (shm, EGL Wayland buffer, DMA-buf, or simple-buffer) at commit time and dispatches to the renderer for import. Buffer sharing is mediated through the Wayland shm pool mechanism and the enabled buffer protocol extensions.<\/p>\n\n\n\n
            sequenceDiagram\n    participant Client as Wayland Client\n    participant WlServer as wl_display Westeros\n    participant Comp as Compositor Thread\n    participant Renderer as Renderer Module\n\n    Client->>WlServer: wl_surface.attach buffer\n    Client->>WlServer: wl_surface.commit\n    WlServer->>Comp: wstISurfaceCommit dispatch\n    Comp->>Renderer: surfaceCommit surface bufferResource\n    Renderer-->>Comp: buffer imported\n    Comp-->>WlServer: schedule repaint\n    WlServer-->>Client: frame callback on next vsync<\/pre><\/div>\n\n\n\n
            VPC Video Path Control Flow:<\/strong><\/p>\n\n\n\n
            sequenceDiagram\n    participant VideoClient as Video Client\n    participant Comp as Compositor Thread\n    participant ParentComp as Parent Compositor nested\n\n    VideoClient->>Comp: vpc_surface.set_geometry x y w h\n    Comp->>Comp: update WstVpcSurface transform\n    Comp->>ParentComp: forward vpc xform via nested connection\n    ParentComp-->>Comp: vpc video_path_change event\n    Comp->>VideoClient: vpc_surface.video_path_change notification<\/pre><\/div>\n\n\n\n
            \n\n\n\n
            Implementation Details<\/h2>\n\n\n\n
            Major HAL APIs Integration<\/h3>\n\n\n\n
            The HAL boundary for Westeros is the renderer module interface. All functions below are called through the WstRenderer<\/code> function pointer table populated by the renderer module’s renderer_init<\/code> entry point.<\/p>\n\n\n\n
            Renderer Module API<\/th>Purpose<\/th>Implementation File<\/th><\/tr><\/thead>
            renderer_init()<\/code><\/td>Entry point called after dlopen<\/code>; populates the WstRenderer<\/code> function table<\/td>westeros-render-gl.cpp<\/code>, westeros-render-embedded.cpp<\/code><\/td><\/tr>
            surfaceCreate()<\/code><\/td>Allocates a per-surface render object (WstRenderSurface<\/code>) within the renderer<\/td>westeros-render-gl.cpp<\/code><\/td><\/tr>
            surfaceCommit()<\/code><\/td>Imports or uploads the Wayland client buffer into the renderer (EGL Wayland buffer, DMA-buf, or shm)<\/td>westeros-render-gl.cpp<\/code>, westeros-render-embedded.cpp<\/code><\/td><\/tr>
            surfaceImportSync()<\/code><\/td>Imports the explicit sync fence for a surface buffer commit<\/td>westeros-render-gl.cpp<\/code><\/td><\/tr>
            surfaceSetGeometry()<\/code><\/td>Sets the position and dimensions of a surface for the next scene update<\/td>westeros-render-gl.cpp<\/code>, westeros-render-embedded.cpp<\/code><\/td><\/tr>
            surfaceSetZOrder()<\/code><\/td>Sets the rendering order of a surface<\/td>westeros-render-gl.cpp<\/code>, westeros-render-embedded.cpp<\/code><\/td><\/tr>
            surfaceSetOpacity()<\/code><\/td>Sets the alpha multiplier for a surface<\/td>westeros-render-gl.cpp<\/code>, westeros-render-embedded.cpp<\/code><\/td><\/tr>
            surfaceSetVisible()<\/code><\/td>Controls whether a surface participates in scene rendering<\/td>westeros-render-gl.cpp<\/code>, westeros-render-embedded.cpp<\/code><\/td><\/tr>
            surfaceSetCrop()<\/code><\/td>Sets the source crop rectangle for a surface<\/td>westeros-render-embedded.cpp<\/code><\/td><\/tr>
            updateScene()<\/code><\/td>Renders all visible surfaces to the output target for the current frame<\/td>westeros-render-gl.cpp<\/code>, westeros-render-embedded.cpp<\/code><\/td><\/tr>
            holePunch()<\/code><\/td>Clears a screen region to allow hardware video overlay to show through<\/td>westeros-render-embedded.cpp<\/code><\/td><\/tr>
            queryDmabufFormats()<\/code> \/ queryDmabufModifiers()<\/code><\/td>Queries supported DMA-buf pixel formats and modifiers from the renderer<\/td>westeros-render-gl.cpp<\/code><\/td><\/tr>
            resolutionChangeBegin()<\/code> \/ resolutionChangeEnd()<\/code><\/td>Signals the renderer before and after an output resolution change<\/td>westeros-render-gl.cpp<\/code><\/td><\/tr>
            renderTerm()<\/code><\/td>Releases all renderer resources at shutdown<\/td>westeros-render-gl.cpp<\/code>, westeros-render-embedded.cpp<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
            Key Implementation Logic<\/h3>\n\n\n\n
              \n
            • State \/ Lifecycle Management<\/strong>: All compositor state is held in WstContext<\/code> (heap-allocated, one per compositor instance). WstCompositorCreate<\/code> allocates and zero-initialises both WstContext<\/code> and WstCompositor<\/code>, sets default frame rate (60 fps), default output size (1280\u00d7720), and default keymap (evdev\/pc105\/us). WstCompositorStart<\/code> spawns the compositor thread; WstCompositorStop<\/code> sets ctx->running = false<\/code> and joins the thread.<\/li>\n\n\n\n
            • Core lifecycle: westeros-compositor.cpp<\/code> \u2014 WstCompositorCreate<\/code>, WstCompositorStart<\/code>, WstCompositorStop<\/code>, WstCompositorDestroy<\/code><\/li>\n\n\n\n
            • Compositor thread body: westeros-compositor.cpp<\/code> \u2014 wstCompositorThread<\/code><\/li>\n\n\n\n
            • Event Processing<\/strong>: Input events injected by the host application are written into WstCompositor::eventQueue[WST_EVENT_QUEUE_SIZE]<\/code> (64 entries, a fixed batch indexed by eventIndex<\/code>). The compositor thread calls wstCompositorProcessEvents<\/code> on each loop iteration, draining the queue and dispatching each event type to the matching handler (wstProcessKeyEvent<\/code>, wstProcessPointerMoveEvent<\/code>, wstProcessTouchDownEvent<\/code>, etc.). Each handler locates the appropriate focused surface via WstKeyboard::focus<\/code>, WstPointer::focus<\/code>, or WstTouch::focus<\/code> and sends the corresponding Wayland protocol event to the client’s resource list.<\/li>\n\n\n\n
            • Error Handling Strategy<\/strong>: API functions return bool<\/code> (true on success). On failure, a descriptive string is stored in WstCompositor::lastErrorDetail<\/code> and retrieved with WstCompositorGetLastErrorDetail<\/code>. Renderer dlopen<\/code> and renderer_init<\/code> failures abort WstCompositorStart<\/code>. Nested connection loss sets compositorAborted<\/code>, which terminates the compositor thread cleanly.<\/li>\n\n\n\n
            • Logging & Diagnostics<\/strong>: The internal wstLog(level, fmt, ...)<\/code> function writes to stderr<\/code>. Verbosity is controlled at startup by the WESTEROS_DEBUG<\/code> environment variable (integer 0\u20136, default 3). Log prefixes are Westeros Fatal<\/code> (0), Westeros Error<\/code> (0), Westeros Warning<\/code> (1), Westeros Info<\/code> (2), Westeros Debug<\/code> (3), and Westeros Trace<\/code> (4\u20136).<\/li>\n<\/ul>\n\n\n\n
              \n\n\n\n
              Configuration<\/h2>\n\n\n\n
              Key Configuration Parameters<\/h3>\n\n\n\n
              Parameter<\/th>Type<\/th>Default<\/th>Description<\/th><\/tr><\/thead>
              WESTEROS_DEBUG<\/code><\/td>int<\/td>3<\/code><\/td>Log verbosity level (0 = fatal\/error only, 3 = info and debug, 6 = full trace). Read once at WstCompositorCreate<\/code>.<\/td><\/tr>
              WAYLAND_DISPLAY<\/code><\/td>string<\/td>wayland-0<\/code><\/td>Name of the Wayland socket created by the compositor, set in westeros-init<\/code> before launch.<\/td><\/tr>
              XDG_RUNTIME_DIR<\/code><\/td>string<\/td>\/run<\/code><\/td>Directory used for the Wayland socket file. westeros-init<\/code> waits up to 60 seconds for this path to become available.<\/td><\/tr>
              WESTEROS_GL_MODE<\/code><\/td>string<\/td>\u2014<\/td>Output mode string (e.g., 3840x2160x60<\/code>) passed to the GL renderer module for display mode selection.<\/td><\/tr>
              WESTEROS_GL_GRAPHICS_MAX_SIZE<\/code><\/td>string<\/td>\u2014<\/td>Maximum graphics plane size (e.g., 1920x1080<\/code>) passed to the GL renderer module.<\/td><\/tr>
              WESTEROS_GL_USE_REFRESH_LOCK<\/code><\/td>int<\/td>\u2014<\/td>When set to 1<\/code>, instructs the GL renderer to synchronise frame generation to display refresh.<\/td><\/tr>
              WESTEROS_VPC_BRIDGE<\/code><\/td>string<\/td>\u2014<\/td>Display name of a compositor to establish a VPC bridge with, used by embedded compositors.<\/td><\/tr>
              WESTEROS_RENDER_GL_FPS<\/code><\/td>\u2014<\/td>\u2014<\/td>Enables frame-rate reporting in the GL renderer module.<\/td><\/tr>
              WESTEROS_FAST_RENDER<\/code><\/td>string<\/td>\u2014<\/td>For embedded composition, names a fast-render shared library implementing delegateUpdateScene<\/code>.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
              Runtime Configuration<\/h3>\n\n\n\n
              The westeros-init<\/code> script selects the renderer module before launching the compositor. Its RENDERER<\/code> assignment overrides any value from \/etc\/default\/westeros-env<\/code>, so change the init script or invoke westeros<\/code> directly when selecting a renderer.<\/p>\n\n\n\n
              To apply supported environment-file changes:<\/p>\n\n\n\n
              systemctl restart westeros<\/p>\n\n\n\n
              The frame rate and display name can also be passed on the command line when invoking the westeros<\/code> binary directly:<\/p>\n\n\n\n
              westeros --renderer \/usr\/lib\/libwesteros_render_gl.so.0 --framerate 60 --display wayland-0<\/pre>\n","protected":false},"excerpt":{"rendered":"
              Westeros is a lightweight Wayland compositor library that enables applications to create one or more […]<\/p>\n","protected":false},"author":28,"featured_media":0,"parent":9844,"menu_order":29,"comment_status":"open","ping_status":"closed","template":"","meta":{"_bbp_topic_count":0,"_bbp_reply_count":0,"_bbp_total_topic_count":0,"_bbp_total_reply_count":0,"_bbp_voice_count":0,"_bbp_anonymous_reply_count":0,"_bbp_topic_count_hidden":0,"_bbp_reply_count_hidden":0,"_bbp_forum_subforum_count":0,"footnotes":""},"class_list":["post-9987","page","type-page","status-publish","hentry"],"yoast_head":"\nWesteros - RDK Documentation Portal | Documentation<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Westeros - RDK Documentation Portal | Documentation\" \/>\n<meta property=\"og:description\" content=\"Westeros is a lightweight Wayland compositor library that enables applications to create one or more […]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/\" \/>\n<meta property=\"og:site_name\" content=\"RDK Documentation Portal | Documentation\" \/>\n<meta property=\"article:modified_time\" content=\"2026-09-22T06:12:22+00:00\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"11 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/\",\"url\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/\",\"name\":\"Westeros - RDK Documentation Portal | Documentation\",\"isPartOf\":{\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/#website\"},\"datePublished\":\"2022-06-21T09:10:37+00:00\",\"dateModified\":\"2026-09-22T06:12:22+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/developer.rdkcentral.com\/documentation\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Documentation\",\"item\":\"https:\/\/developer.rdkcentral.com\/documentation\/\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"RDK Video\",\"item\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/\"},{\"@type\":\"ListItem\",\"position\":4,\"name\":\"Components\",\"item\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/\"},{\"@type\":\"ListItem\",\"position\":5,\"name\":\"Westeros\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/#website\",\"url\":\"https:\/\/developer.rdkcentral.com\/documentation\/\",\"name\":\"RDK Documentation Portal | Documentation\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/developer.rdkcentral.com\/documentation\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Westeros - RDK Documentation Portal | Documentation","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/","og_locale":"en_US","og_type":"article","og_title":"Westeros - RDK Documentation Portal | Documentation","og_description":"Westeros is a lightweight Wayland compositor library that enables applications to create one or more […]","og_url":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/","og_site_name":"RDK Documentation Portal | Documentation","article_modified_time":"2026-09-22T06:12:22+00:00","twitter_card":"summary_large_image","twitter_misc":{"Est. reading time":"11 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/","url":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/","name":"Westeros - RDK Documentation Portal | Documentation","isPartOf":{"@id":"https:\/\/developer.rdkcentral.com\/documentation\/#website"},"datePublished":"2022-06-21T09:10:37+00:00","dateModified":"2026-09-22T06:12:22+00:00","breadcrumb":{"@id":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/westeros\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/developer.rdkcentral.com\/documentation\/"},{"@type":"ListItem","position":2,"name":"Documentation","item":"https:\/\/developer.rdkcentral.com\/documentation\/"},{"@type":"ListItem","position":3,"name":"RDK Video","item":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/"},{"@type":"ListItem","position":4,"name":"Components","item":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_video_documentation\/components\/"},{"@type":"ListItem","position":5,"name":"Westeros"}]},{"@type":"WebSite","@id":"https:\/\/developer.rdkcentral.com\/documentation\/#website","url":"https:\/\/developer.rdkcentral.com\/documentation\/","name":"RDK Documentation Portal | Documentation","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/developer.rdkcentral.com\/documentation\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"}]}},"_links":{"self":[{"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages\/9987","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/users\/28"}],"replies":[{"embeddable":true,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/comments?post=9987"}],"version-history":[{"count":4,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages\/9987\/revisions"}],"predecessor-version":[{"id":13039,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages\/9987\/revisions\/13039"}],"up":[{"embeddable":true,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages\/9844"}],"wp:attachment":[{"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/media?parent=9987"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}