GCM System - PSL1GHT

The GCM (Graphics Command Management) system provides low-level control over the RSX graphics processor, including command buffer management, display configuration, memory mapping, and rendering operations.

Context Initialization

gcmInitBody

Initialize the RSX/GCM context.

s32 gcmInitBody(gcmContextData **ctx, const u32 cmdSize, const u32 ioSize, const void *ioAddress);

ctx

gcmContextData**

required

Pointer to receive the effective address of the allocated context structure

cmdSize

u32

required

Command buffer size in bytes

ioSize

u32

required

IO buffer size in bytes

ioAddress

const void*

required

Pointer to allocated IO buffer

return

s32

Returns 0 on success, nonzero on error

gcmGetConfiguration

Retrieve the current RSX configuration.

s32 gcmGetConfiguration(gcmConfiguration *config);

config

gcmConfiguration*

required

Pointer to configuration structure to be filled

return

s32

Returns 0 on success, nonzero on error

gcmConfiguration Structure

typedef struct _gcmCfg {
    void *localAddress;    // Effective start address of RSX memory
    void *ioAddress;       // Effective start address of I/O mapped main memory
    u32 localSize;         // Maximum available RSX memory size
    u32 ioSize;            // Maximum available I/O mapped memory size
    u32 memoryFreq;        // RSX memory clock frequency
    u32 coreFreq;          // RSX core clock frequency
} gcmConfiguration;

Example

gcmConfiguration config;
gcmGetConfiguration(&config);
printf("RSX Memory: %d MB\n", config.localSize / (1024*1024));
printf("Core Freq: %d MHz\n", config.coreFreq / 1000000);

Memory Management

gcmAddressToOffset

Convert an effective address in RSX memory to an offset.

s32 gcmAddressToOffset(const void *address, u32 *offset);

address

const void*

required

Effective address to convert

offset

u32*

required

Pointer to receive the offset value

return

s32

Returns 0 on success, nonzero on error

gcmIoOffsetToAddress

Convert an offset to an effective address in RSX memory.

s32 gcmIoOffsetToAddress(u32 offset, void **address);

offset

u32

required

Offset to convert

address

void**

required

Pointer to receive the effective address

return

s32

Returns 0 on success, nonzero on error

gcmMapMainMemory

Map a memory block in main memory for RSX access.

s32 gcmMapMainMemory(const void *address, const u32 size, u32 *offset);

address

const void*

required

Pointer to the block to be mapped

size

u32

required

Size of the block in bytes

offset

u32*

required

Pointer to receive the mapped offset value

return

s32

Returns 0 on success, nonzero on error

Example

// Map main memory buffer for RSX access
void *buffer = memalign(1024*1024, 4*1024*1024);
u32 offset;
gcmMapMainMemory(buffer, 4*1024*1024, &offset);

gcmMapEaIoAddress

Map an effective address to an IO address.

s32 gcmMapEaIoAddress(const void *ea, const u32 io, const u32 size);

const void*

required

Effective address to map

u32

required

IO address

size

u32

required

Size in bytes

return

s32

Returns 0 on success, nonzero on error

gcmUnmapIoAddress

Unmap a previously mapped IO address.

s32 gcmUnmapIoAddress(const u32 io);

u32

required

IO address to unmap

return

s32

Returns 0 on success, nonzero on error

gcmMapLocalMemory

Map local RSX memory.

s32 gcmMapLocalMemory(void **address, u32 *size);

address

void**

required

Pointer to receive the mapped address

size

u32*

required

Pointer to receive the size of mapped memory

return

s32

Returns 0 on success, nonzero on error

gcmGetMaxIoMapSize

Get the maximum IO map size available.

u32 gcmGetMaxIoMapSize();

return

u32

Maximum IO map size in bytes

Display Management

gcmSetDisplayBuffer

Configure a display framebuffer.

s32 gcmSetDisplayBuffer(const u8 bufferId, const u32 offset, const u32 pitch, const u32 width, const u32 height);

bufferId

required

Buffer ID (0-7)

offset

u32

required

Offset of the buffer in video memory (from rsxAddressToOffset)

pitch

u32

required

Size of a buffer line in bytes (width * bytes_per_pixel)

width

u32

required

Buffer width in pixels

height

u32

required

Buffer height in pixels

return

s32

Returns 0 on success, nonzero on error

Example

// Configure two display buffers for double buffering
for (int i = 0; i < 2; i++) {
    void *buffer = rsxMemalign(64, 1920 * 1080 * 4);
    u32 offset;
    rsxAddressToOffset(buffer, &offset);
    gcmSetDisplayBuffer(i, offset, 1920 * 4, 1920, 1080);
}

gcmSetFlip

Enqueue a flip command into the command buffer.

s32 gcmSetFlip(gcmContextData *context, const u8 bufferId);

context

gcmContextData*

required

Pointer to the context object

bufferId

required

Framebuffer ID to flip to (as configured with gcmSetDisplayBuffer)

return

s32

Returns 0 on success, nonzero on error

gcmSetFlipMode

Set the flip synchronization mode.

void gcmSetFlipMode(const u32 mode);

mode

u32

required

Flip mode: GCM_FLIP_HSYNC, GCM_FLIP_VSYNC, or GCM_FLIP_HSYNC_AND_BREAK_EVERYTHING

Use GCM_FLIP_VSYNC to synchronize with vertical refresh and prevent tearing.

gcmSetWaitFlip

Wait for a flip to complete.

void gcmSetWaitFlip(gcmContextData *context);

context

gcmContextData*

required

Pointer to the context object

gcmGetFlipStatus

Get the flip status.

u32 gcmGetFlipStatus();

return

u32

Returns nonzero if a flip occurred, 0 otherwise

Once a flip has occurred, you must call gcmResetFlipStatus() before querying again.

gcmResetFlipStatus

Reset the flip status.

void gcmResetFlipStatus();

Call this after a flip has completed to prepare for the next flip query.

gcmSetPrepareFlip

Perform preprocessing for display output.

u32 gcmSetPrepareFlip(gcmContextData *context, const u8 id);

context

gcmContextData*

required

Pointer to context object

required

Buffer ID

return

u32

Returns status value

gcmGetLastFlipTime

Get the timestamp of the last flip.

s64 gcmGetLastFlipTime();

return

s64

Timestamp of last flip

gcmSetFlipImmediate

Perform an immediate flip without waiting for VSync.

s32 gcmSetFlipImmediate(const u8 id);

required

Buffer ID to flip to

return

s32

Returns 0 on success, nonzero on error

gcmGetCurrentDisplayBufferId

Get the currently displayed buffer ID.

s32 gcmGetCurrentDisplayBufferId(u8 *id);

u8*

required

Pointer to receive the current buffer ID

return

s32

Returns 0 on success, nonzero on error

gcmGetVBlankCount

Get the VBlank count.

u64 gcmGetVBlankCount();

return

u64

Current VBlank count

Event Handlers

gcmSetVBlankHandler

void gcmSetVBlankHandler(void (*handler)(const u32 head));

handler

void (*)(const u32 head)

required

Callback function (NULL to cancel)

Example

void vblank_handler(const u32 head) {
    // Called every VBlank
}

gcmSetVBlankHandler(vblank_handler);

gcmSetFlipHandler

void gcmSetFlipHandler(void (*handler)(const u32 head));

handler

void (*)(const u32 head)

required

Callback function (NULL to cancel)

gcmSetGraphicsHandler

void gcmSetGraphicsHandler(void (*handler)(const u32 val));

handler

void (*)(const u32 val)

required

Callback function (NULL to cancel)

gcmSetUserHandler

void gcmSetUserHandler(void (*handler)(const u32 cause));

handler

void (*)(const u32 cause)

required

Callback function

Command Buffer Control

gcmGetControlRegister

Obtain registers for controlling the command buffer.

gcmControlRegister* gcmGetControlRegister();

return

gcmControlRegister*

Pointer to control register structure

gcmControlRegister Structure

typedef struct _gcmCtrlRegister {
    vu32 put;    // PUT register
    vu32 get;    // GET register
    vu32 ref;    // REF register (initial value: 0xFFFFFFFF)
} gcmControlRegister;

gcmSetDefaultCommandBuffer

Set the default command buffer.

void gcmSetDefaultCommandBuffer();

Render Operations

gcmSetTile

Configure a tile region.

void gcmSetTile(const u8 index, const u8 location, const u32 offset, const u32 size, 
                const u32 pitch, const u8 comp, const u16 base, const u8 bank);

index

required

Tile index (0-14)

location

required

Memory location (GCM_LOCATION_RSX or GCM_LOCATION_CELL)

offset

u32

required

Memory offset

size

u32

required

Tile size

pitch

u32

required

Tile pitch

comp

required

Compression mode

base

u16

required

Base value

bank

required

Bank value

gcmSetInvalidateTile

Invalidate a tile region.

void gcmSetInvalidateTile(const u8 index);

index

required

Tile index to invalidate

gcmBindTile

Bind a tile region.

s32 gcmBindTile(const u8 index);

index

required

Tile index to bind

return

s32

Returns 0 on success, nonzero on error

gcmUnbindTile

Unbind a tile region.

s32 gcmUnbindTile(const u8 index);

index

required

Tile index to unbind

return

s32

Returns 0 on success, nonzero on error

gcmSetZcull

Configure Z-culling.

void gcmSetZcull(const u8 index, const u32 offset, const u32 width, const u32 height,
                 const u32 cullStart, const u32 zFormat, const u32 aaFormat, 
                 const u32 zCullDir, const u32 zCullFormat, const u32 sFunc, 
                 const u32 sRef, const u32 sMask);

index

required

Zcull region index

offset

u32

required

Memory offset

width

u32

required

Width in pixels

height

u32

required

Height in pixels

cullStart

u32

required

Cull start offset

zFormat

u32

required

Depth format (GCM_ZCULL_Z16 or GCM_ZCULL_Z24S8)

aaFormat

u32

required

Anti-aliasing format

zCullDir

u32

required

Z-cull direction (GCM_ZCULL_LESS or GCM_ZCULL_GREATER)

zCullFormat

u32

required

Z-cull format

sFunc

u32

required

Stencil function

sRef

u32

required

Stencil reference value

sMask

u32

required

Stencil mask

gcmGetLabelAddress

Get the address of a specified label.

u32* gcmGetLabelAddress(const u8 index);

index

required

Label index

return

u32*

Pointer to the label address

gcmGetReport

Get a report value.

u32 gcmGetReport(const u32 type, const u32 index);

type

u32

required

Report type

index

u32

required

Report index

return

u32

Report value

gcmGetTimeStamp

Get a timestamp value.

u64 gcmGetTimeStamp(const u32 index);

index

u32

required

Timestamp index

return

u64

Timestamp value

Hardware Cursor

gcmInitCursor

Initialize hardware cursor support.

s32 gcmInitCursor();

return

s32

Returns 0 on success, nonzero on error

gcmSetCursorEnable

Enable the hardware cursor.

s32 gcmSetCursorEnable();

return

s32

Returns 0 on success, nonzero on error

gcmSetCursorDisable

Disable the hardware cursor.

s32 gcmSetCursorDisable();

return

s32

Returns 0 on success, nonzero on error

gcmSetCursorPosition

Set the cursor position.

s32 gcmSetCursorPosition(const s32 x, const s32 y);

s32

required

X coordinate

s32

required

Y coordinate

return

s32

Returns 0 on success, nonzero on error

gcmSetCursorImageOffset

Set the cursor image offset.

s32 gcmSetCursorImageOffset(const u32 offset);

offset

u32

required

Image offset in video memory

return

s32

Returns 0 on success, nonzero on error

gcmUpdateCursor

Update the cursor display.

s32 gcmUpdateCursor();

return

s32

Returns 0 on success, nonzero on error

Constants

Memory Locations

GCM_LOCATION_RSX (0) - Buffer in RSX video memory
GCM_LOCATION_CELL (1) - Buffer in main memory
GCM_LOCATION_REPORT (2) - Buffer in report memory

Flip Modes

GCM_FLIP_HSYNC (1) - Flip on horizontal sync (accurate)
GCM_FLIP_VSYNC (2) - Flip on vertical sync
GCM_FLIP_HSYNC_AND_BREAK_EVERYTHING (3) - Flip on horizontal sync (inaccurate)

Surface Formats

GCM_SURFACE_X8R8G8B8 (5) - 32-bit color without alpha
GCM_SURFACE_A8R8G8B8 (8) - 32-bit color with alpha
GCM_SURFACE_R5G6B5 (3) - 16-bit color

Depth Formats

GCM_SURFACE_ZETA_Z16 (1) - 16-bit depth buffer
GCM_SURFACE_ZETA_Z24S8 (2) - 24-bit depth + 8-bit stencil

Graphics APIs

Input APIs

Audio APIs

Network APIs

System APIs

System Utility APIs

Media APIs

Device APIs

SPU APIs

Math Libraries

​Context Initialization

​gcmInitBody

​gcmGetConfiguration

​Memory Management

​gcmAddressToOffset

​gcmIoOffsetToAddress

​gcmMapMainMemory

​gcmMapEaIoAddress

​gcmUnmapIoAddress

​gcmMapLocalMemory

​gcmGetMaxIoMapSize

​Display Management

​gcmSetDisplayBuffer

​gcmSetFlip

​gcmSetFlipMode

​gcmSetWaitFlip

​gcmGetFlipStatus

​gcmResetFlipStatus

​gcmSetPrepareFlip

​gcmGetLastFlipTime

​gcmSetFlipImmediate

​gcmGetCurrentDisplayBufferId

​gcmGetVBlankCount

​Event Handlers

​gcmSetVBlankHandler

​gcmSetFlipHandler

​gcmSetGraphicsHandler

​gcmSetUserHandler

​Command Buffer Control

​gcmGetControlRegister

​gcmSetDefaultCommandBuffer

​Render Operations

​gcmSetTile

​gcmSetInvalidateTile

​gcmBindTile

​gcmUnbindTile

​gcmSetZcull

​gcmGetLabelAddress

​gcmGetReport

​gcmGetTimeStamp

​Hardware Cursor

​gcmInitCursor

​gcmSetCursorEnable

​gcmSetCursorDisable

​gcmSetCursorPosition

​gcmSetCursorImageOffset

​gcmUpdateCursor

​Constants

​Memory Locations

​Flip Modes

​Surface Formats

​Depth Formats

​See Also

Build docs developers (and LLMs) love

Context Initialization

gcmInitBody

gcmGetConfiguration

Memory Management

gcmAddressToOffset

gcmIoOffsetToAddress

gcmMapMainMemory

gcmMapEaIoAddress

gcmUnmapIoAddress

gcmMapLocalMemory

gcmGetMaxIoMapSize

Display Management

gcmSetDisplayBuffer

gcmSetFlip

gcmSetFlipMode

gcmSetWaitFlip

gcmGetFlipStatus

gcmResetFlipStatus

gcmSetPrepareFlip

gcmGetLastFlipTime

gcmSetFlipImmediate

gcmGetCurrentDisplayBufferId

gcmGetVBlankCount

Event Handlers

gcmSetVBlankHandler

gcmSetFlipHandler

gcmSetGraphicsHandler

gcmSetUserHandler

Command Buffer Control

gcmGetControlRegister

gcmSetDefaultCommandBuffer

Render Operations

gcmSetTile

gcmSetInvalidateTile

gcmBindTile

gcmUnbindTile

gcmSetZcull

gcmGetLabelAddress

gcmGetReport

gcmGetTimeStamp

Hardware Cursor

gcmInitCursor

gcmSetCursorEnable

gcmSetCursorDisable

gcmSetCursorPosition

gcmSetCursorImageOffset

gcmUpdateCursor

Constants

Memory Locations

Flip Modes

Surface Formats

Depth Formats

See Also