Synopsis

void BltPipeResourceRastPort(
         PipeHandle_t pipe,
         struct pipe_resource * srcPipeResource,
         LONG xSrc,
         LONG ySrc,
         struct RastPort * destRP,
         LONG xDest,
         LONG yDest,
         LONG xSize,
         LONG ySize );

Function

Copies part of pipe resource onto rast port. Clips output by using layers of
rastport.

Inputs

srcPipeResource - Copy from this pipe resource.
xSrc, ySrc - This is the upper left corner of the area to copy.
destRP - Destination RastPort.
xDest, yDest - Upper left corner where to place the copy
xSize, ySize - The size of the area to copy

Synopsis

PipeHandle_t CreatePipe(
         struct TagItem * tags );

PipeHandle_t CreatePipeTags(
         TAG tag, ... );

Function

Instantiates a gallium pipe.

Inputs

tags - a pointer to tags to be used during creation.

Tags

CPS_PipeFriendBitmap - a bitmap our pipe screen will target.
CPS_PipeScreenDriver * - where to store the driver.
CPS_GalliumInterfaceVersion - Indicates a version of gallium interface
    that a client is expected to receive. The client expected version
    must ideally match with the version that the driver provides,
    because gallium interface is not backwards compatible. This tag is
    required. Unless otherwise needed, the value
    GALLIUM_INTERFACE_VERSION should be passed.
    See also CreatePipeV.

Result

A valid pipe instance or NULL if creation was not successful.

Synopsis

struct pipe_screen * CreatePipeScreen(
         PipeHandle_t pipe );

Function

Creates a gallium pipe screen.

Inputs

pipe - a pipe handle created using CreatePipe().

Result

A valid pipe screen instance or NULL if creation was not successful.

Synopsis

APTR CreateScanoutFrameBuffer(
         PipeHandle_t pipe,
         struct Window * window,
         struct TagItem * tags );

APTR CreateScanoutFrameBufferTags(
         PipeHandle_t pipe,
         struct Window * window,
         TAG tag, ... );

Function

Creates a scan-out framebuffer for a rectangle of a window: 2 or 3
colour buffers in display memory that the window's screen display
shows itself (through a hardware plane when the compositor grants
one, blitted through the window's visible region otherwise), each
available to the pipe as a pipe_resource to render into. The
framebuffer follows the window: gallium.library tracks the window's
layer and keeps the surface's position and visible shape current.

Inputs

pipe   - the pipe handle from CreatePipe()
window - the window; its screen's display shows the framebuffer
tags   - SFB_Left, SFB_Top, SFB_Width, SFB_Height (required: the
         rectangle relative to window->WLayer, i.e. RastPort
         coordinates), SFB_PipeFormat (required), SFB_PipeScreen
         (required: the PipeScreen_t of this pipe), SFB_Buffers
         (2 or 3, default 2), SFB_NoWait (see <gallium/gallium.h>)

Result

The framebuffer handle, or NULL when the display cannot show the
format through a plane (HIDD_Display_QueryScanout without
SCF_PLANE), the pipe driver cannot import scan-out buffers
(moHidd_Gallium_ResourceFromBitMap), or the surface cannot be
attached (e.g. the screen is not shown yet). The caller then keeps
BltPipeResourceRastPort().

Notes

Rendering goes to the buffer SwapScanoutFrameBuffer() returned (the
SFBA_BackBuffer at creation); the pipe_resource of buffer n is
GetScanoutFrameBufferResource(fb, n). There is no resize: destroy
and create a new framebuffer when the rectangle changes.

The framebuffer must be destroyed before the window closes; as a
safety net gallium.library detaches it when the window closes
(SNOTIFY_BEFORE_CLOSEWINDOW), after which swaps show nothing and
SFBA_Attached is FALSE.

See also

GetScanoutFrameBufferResource() SwapScanoutFrameBuffer() DestroyScanoutFrameBuffer() GetScanoutFrameBufferAttr()

Synopsis

void DestroyPipe(
         PipeHandle_t pipe );

Function

Destroys a peviously created pipe.

Inputs

pipe - a pipe handle created using CreatePipe().

Synopsis

void DestroyPipeScreen(
         PipeHandle_t pipe,
         struct pipe_screen * pscreen );

Function

Disposes the pipe screen

Inputs

handle - a pointer to pipe screen structure. A NULL pointer will be
    ignored.

Result

The pipe screen is freed. Don't use it anymore.

Synopsis

void DestroyScanoutFrameBuffer(
         APTR fb );

Function

Detaches the surface from the display and frees the framebuffer and
its resources. Resources the caller still references stay valid
until its last reference is dropped, but their memory is no longer
shown.

Inputs

fb - the framebuffer (NULL is ignored)

Synopsis

APTR FindScanoutFrameBuffer(
         struct Window * window );

Function

Returns the scan-out framebuffer currently attached to a window, if
any (the first one in attach order). Meant for diagnostics (a GL
program asking whether its context presents through scan-out); the
handle belongs to whoever created it and is only valid while that
owner keeps it.

Inputs

window - the window

Result

The framebuffer handle or NULL.

Synopsis

IPTR GetScanoutFrameBufferAttr(
         APTR fb,
         ULONG attr );

Function

Queries a scan-out framebuffer.

Inputs

fb   - the framebuffer
attr - SFBA_* (see <gallium/gallium.h>)

Result

The value, 0 for an unknown attribute or a NULL framebuffer.

Synopsis

APTR GetScanoutFrameBufferResource(
         APTR fb,
         ULONG buffer );

Function

Returns the pipe_resource that aliases colour buffer `buffer` of a
scan-out framebuffer.

Inputs

fb     - the framebuffer
buffer - 0 .. SFBA_Buffers - 1

Result

struct pipe_resource *, owned by the framebuffer (take your own
reference with pipe_resource_reference() if you keep it), or NULL.

Synopsis

BOOL SetScanoutFrameBufferAttr(
         APTR fb,
         ULONG attr,
         IPTR value );

Function

Changes a scan-out framebuffer setting while it is in use.

SFBA_NoWait - TRUE: SwapScanoutFrameBuffer() queues the flip and
    returns at once (rendering is not tied to the refresh rate; a
    frame finished before the display took the previous one is not
    shown). FALSE: each swap waits until its buffer is on screen.
    Only a framebuffer with 3 or more buffers can stop waiting:
    with 2 the buffer rendered next is the one being displaced.

Inputs

fb    - the framebuffer
attr  - SFBA_NoWait
value - the new value

Result

TRUE if the setting was applied.

Synopsis

ULONG SwapScanoutFrameBuffer(
         APTR fb );

Function

Shows the buffer that was rendered last (the one the previous call,
or SFBA_BackBuffer at creation, handed out) and returns the index
of the buffer to render next. The caller must have flushed its
rendering to the pipe before the call. With 2 buffers the call
waits until the displaced buffer is off scan-out (unless
SFB_NoWait); with 3 it returns at once and the returned buffer is
one that is neither scanned out nor waiting to be. If the display
has not taken the previous buffer yet, the one just rendered is
not shown and is returned again, so the newest frame goes up at
the next swap after the display is ready.

Inputs

fb - the framebuffer

Result

Index of the buffer to render next.