Graphics & Surfaces

Surface, not framebuffer

An application binds a Surface and draws in its local coordinate system. The backend decides whether that surface is a window, image, physical display, texture, overlay, remote session, or terminal.

Presentation may copy, composite, queue, or redraw damaged regions. Application code does not depend on framebuffer addresses, buffering count, monitor topology, or GPU availability.

Raster policy is ArcoBASIC

The compiler provides typed address arithmetic, volatile writes, and a memory barrier. Bounds checking, clipping, scan loops, pixel offsets, and color choice remain visible ArcoBASIC source.

ArcoBASICArcology source: clipped software rectangle

' This drawing routine runs directly against a UEFI framebuffer.
#PROFILE UEFI
#TARGET X86_64
#RUNTIME NONE

FUNCTION FillRectClipped(framebuffer AS MMIOPTR, width AS U32, height AS U32, stride AS U32, x AS U32, y AS U32, rectWidth AS U32, rectHeight AS U32, color AS U32) AS U64
    ' Clip the rectangle so no pixel is written beyond the surface.
    LET endX AS U32 = x + rectWidth
    LET endY AS U32 = y + rectHeight
    IF x < width AND y < height THEN
        IF endX > width THEN endX = width
        IF endY > height THEN endY = height
        LET row AS U32 = y
        WHILE row < endY
            LET column AS U32 = x
            WHILE column < endX
                ' Convert the friendly row and column into a byte offset.
                LET pixelOffset AS U32 = (row * stride + column) * 4
                MEMORY.Write32(ADDRESS.Offset(framebuffer, pixelOffset), color)
                column = column + 1
            WEND
            row = row + 1
        WEND
    END IF
    ' Make every completed pixel write visible before returning.
    CPU.MemoryBarrier
    RETURN 0
END FUNCTION

Current boundary

The freestanding graphics substrate can fill mapped GOP surfaces, draw clipped primitives, pack RGB/BGR colors, render diagnostic glyphs, and continue rendering after the APS CR3 cutover.

The public opaque Surface API exists in the hosted reference runtime. Moving construction, clipping, resource registration, and presentation fully behind the freestanding Surface library remains ongoing work.

Abstract the destination, not just the operation

A Surface hides whether drawing lands on a window, an image, a physical display, or a remote session behind one coordinate system. FillRectClipped does not know or care which of those it is writing into. That separation, what you draw versus where it ends up, is worth more broadly than this one graphics stack.

Give application code a stable local abstraction, here a Surface with its own coordinate system, and let the backend decide how that maps onto whatever the real destination happens to be. Code written against the abstraction keeps working when the destination changes underneath it.
Push bounds checking and clipping into the language layer people actually read and can review, rather than hiding it in compiler-provided primitives nobody inspects. FillRectClipped clips visibly, in source, precisely because a reviewer should be able to see the safety property, not just trust that it exists.
Let a status section admit exactly which pieces are proven and which are still being moved behind the abstraction. Naming the gap between "the substrate can already do this" and "the public API fully owns this yet" is what keeps a roadmap honest instead of aspirational.

LEARNING LAYER

Key terms, in plain language

You do not need a systems background to follow the work. These are the specialized terms used on this page.

Surface: An abstract destination for drawing. It might eventually represent a window, image, texture, remote display, or physical screen without application code changing.
Framebuffer: A region of memory whose values become pixels on a display. Writing a color value into the right location changes the corresponding pixel.
GOPGraphics Output Protocol: The UEFI service that exposes a basic display framebuffer before a full graphics driver exists.
MMIOMemory-Mapped Input/Output: A way to control a hardware device by reading and writing special address ranges as if they were memory. A framebuffer is a common example.
Raster graphics: Drawing an image as a grid of individual pixels. Rectangle filling, clipping, and pixel addressing are basic raster operations.