nCine::RHI::GXM::GxmDevice class
#include <nCine/Graphics/RHI/GXM/GxmDevice.h>

Pipeline-state and draw-call facade of the sceGxm backend (aliased as RHI::Device).

Exposes the OpenGL device's surface (blending, depth, cull, scissor, viewport, clear and the draw calls) so the backend-neutral render pipeline drives it unchanged, and owns the whole sceGxm session behind it: the rendering context and its ring buffers, the shader patcher, the display buffers with their sync objects and the display queue that scans them out.

Three properties of the hardware shape everything below.

sceGxm renders in scenes.** The PowerVR SGX is a tile-based deferred renderer: primitives are binned, then each 32x32 tile is shaded once and written out. A scene (sceGxmBeginScene() ... sceGxmEndScene()) is one such pass over one surface, so a scene is opened lazily by the first clear or draw that follows a target change (EnsureScene()) and closed when the target changes again or the frame is presented. Because the tile buffer's colour starts undefined rather than loaded, there is no "clear the surface" operation to issue mid-scene: Clear() draws a full-screen quad with a built-in shader, which is what the clear costs on this architecture (and what OpenGL|ES drivers do here internally too).

That undefined start is also why re-entering a surface within a frame would silently discard what an earlier scene drew into it. The pipeline does not do this - measured on the console, the screen surface takes exactly one scene per frame, and a render target takes one per pass it is the target of

  • but it is the constraint any change to the viewport chain has to respect.

    sceGxm only draws indexed.** There is no glDrawArrays equivalent - every sceGxmDraw() consumes index data - so the device keeps one shared, GPU-visible buffer of increasing indices (0, 1, 2, ...) and hands a window of it to the non-indexed draws, which reproduces glDrawArrays(first, count) exactly. The two vertex-ID-free sprite layouts are served the same way: the shaders the Cg emitter produces read the quad corner (and the batched instance index) from vertex attributes rather than gl_VertexID, so the device also owns the two small static streams that feed them (see GetQuadCornerStream()).

    The display scans out top-down.** The engine renders in the OpenGL convention, and this backend replays it faithfully: every viewport is programmed with a positive Y scale, so clip -Y lands on row 0 and every surface - the screen and each off-screen render target - is stored bottom-up exactly like OpenGL. That is what keeps a texture's V axis and its viewport's Y axis pointing the same way, so an off-screen round trip does not flip the image (the property that makes the scene composite and the directly drawn HUD agree). The scan-out then needs the one correction that convention implies: "screen" (no render target bound) is an intermediate surface, and PresentFrame() flips it into the display buffer with a built-in shader - the same single OpenGL-to-native flip the Direct3D 11 backend does with its present blit, which also scales the logical resolution up to the panel for free.

Public types

struct ScissorState
struct BlendingState
struct DepthTestState
struct CullFaceState
struct DisplayQueueCallbackData
What the display-queue callback needs to hand one finished buffer to the display controller.

Public static variables

static std::uint32_t MaxBatchSize constexpr
Largest batch the GetBatchedCornerStream() covers (the 64 KB uniform-block budget divided by the smallest instance stride).
static std::int32_t DisplayWidth constexpr
The panel's fixed width in pixels.
static std::int32_t DisplayHeight constexpr
The panel's fixed height in pixels.
static std::int32_t DisplayStride constexpr
Stride of a display buffer in pixels (the display controller requires a 64-pixel aligned stride).

Public static functions

static void SetBlendingEnabled(bool enabled)
static void SetBlendingFactors(nCine::BlendingFactor srcRgb, nCine::BlendingFactor dstRgb, nCine::BlendingFactor srcAlpha, nCine::BlendingFactor dstAlpha)
static auto GetBlendingState() -> BlendingState
static void SetBlendingState(const BlendingState& state)
static void SetDepthTestEnabled(bool enabled)
static void SetDepthMaskEnabled(bool enabled)
static auto GetDepthTestState() -> DepthTestState
static void SetDepthTestState(const DepthTestState& state)
static void SetCullFaceEnabled(bool enabled)
static auto GetCullFaceState() -> CullFaceState
static void SetCullFaceState(const CullFaceState& state)
static auto GetScissorState() -> ScissorState
static void SetScissorState(const ScissorState& state)
static void SetScissor(const Recti& rect)
static void SetScissorTestEnabled(bool enabled)
static auto GetViewport() -> Recti
static void SetViewport(const Recti& rect)
static void InitViewport(std::int32_t x, std::int32_t y, std::int32_t width, std::int32_t height)
static auto GetClearColor() -> Colorf
static void SetClearColor(const Colorf& color)
static void Clear(ClearFlags flags)
static void DrawArrays(PrimitiveType primitive, std::int32_t firstVertex, std::int32_t numVertices)
static void DrawArraysInstanced(PrimitiveType primitive, std::int32_t firstVertex, std::int32_t numVertices, std::int32_t numInstances)
static void DrawElements(PrimitiveType primitive, std::uint32_t numIndices, IndexFormat indexFormat, std::uintptr_t indexOffset, std::int32_t baseVertex)
static void DrawElements(PrimitiveType primitive, std::uint32_t numIndices, std::uintptr_t indexOffset, std::int32_t baseVertex)
static void DrawElementsInstanced(PrimitiveType primitive, std::uint32_t numIndices, IndexFormat indexFormat, std::uintptr_t indexOffset, std::int32_t numInstances, std::int32_t baseVertex)
static void DrawElementsInstanced(PrimitiveType primitive, std::uint32_t numIndices, std::uintptr_t indexOffset, std::int32_t numInstances, std::int32_t baseVertex)
static auto InsertFence() -> FenceHandle
static void DeleteFence(FenceHandle& fence)
static auto ClientWaitFence(FenceHandle fence, std::uint64_t timeoutNs) -> bool
static void SetupInitialState()
static void BindProgram(GxmShaderProgram* program)
Records the currently bound shader program.
static auto CurrentProgram() -> GxmShaderProgram*
Returns the currently bound shader program.
static void BindTexture(std::uint32_t unit, const GxmTexture* texture)
Records the texture bound to a texture unit.
static void UnbindTexture(const GxmTexture* texture)
Clears a texture from every unit it is bound to (called from ~GxmTexture to avoid a dangling pointer).
static auto GetBoundTexture(std::uint32_t unit) -> const GxmTexture*
Returns the texture bound to a texture unit.
static void BindUniformRange(std::uint32_t index, const std::uint8_t* data, std::uint32_t size)
Records the host data range bound to a uniform binding point.
static void GetUniformRange(std::uint32_t index, const std::uint8_t*& data, std::uint32_t& size)
Returns the host data range bound to a uniform binding point (read by the draw path).
static void UnbindRenderTarget(const GxmRenderTarget* renderTarget)
Clears a render target from the device if it is the current one (called from ~GxmRenderTarget).
static void SetRenderTarget(GxmRenderTarget* renderTarget)
Records the current draw render target (its bound color attachments receive the pixels).
static void OnProgramDestroyed(const GxmShaderProgram* program)
Clears a destroyed program from the device's current-program tracking (called from ~GxmShaderProgram).
static void FinishScene()
Ends the scene currently being recorded, if any.
static auto GetShaderPatcher() -> SceGxmShaderPatcher*
Returns the shader patcher every program creates its vertex/fragment programs through.
static auto GetContext() -> SceGxmContext*
Returns the rendering context, or nullptr before CreateSwapchain().
static auto GetSceneCounter() -> std::uint32_t
Monotonic count of presented frames (used to detect resources still referenced by the current frame).
static auto GetQuadCornerStream() -> const void*
Returns the static vertex stream feeding aQuadCorner for the 4-vertex sprite strip.
static auto GetBatchedCornerStream() -> const void*
Returns the static vertex stream feeding aQuadCorner + aInstanceIndex for batched sprites.
static auto CreateSwapchain(void* windowHandle, std::int32_t width, std::int32_t height, bool vsync) -> bool
Brings up the whole sceGxm session and the display queue.
static void DestroySwapchain()
Tears the session down (finishes the display queue, then releases everything in creation order).
static void ResizeSwapchain(std::int32_t width, std::int32_t height)
No-op: the panel resolution is fixed (the logical resolution is a render-target size, not a swap-chain one).
static void PresentFrame()
Flips the intermediate screen surface into the next display buffer and queues it for scan-out.
static auto CreateSecondarySwapchain(void* windowHandle, std::int32_t width, std::int32_t height) -> void*
Not supported on this platform (returns nullptr).
static void DestroySecondarySwapchain(void* handle)
Not supported on this platform.
static void ResizeSecondarySwapchain(void* handle, std::int32_t width, std::int32_t height)
Not supported on this platform.
static void BeginSecondaryFrame(void* handle, bool clear)
Not supported on this platform.
static void EndSecondaryFrame()
Not supported on this platform.
static void PresentSecondaryFrame(void* handle)
Not supported on this platform.
static auto GetMaxTextureDimension() -> std::int32_t constexpr
Returns the largest supported 2D texture dimension.
static auto GetUniformBufferOffsetAlignment() -> std::int32_t constexpr
Byte alignment the engine suballocates bound uniform ranges with (one std140 vec4).

Constructors, destructors, conversion operators

GxmDevice() deleted
~GxmDevice() deleted

Function documentation

static void nCine::RHI::GXM::GxmDevice::FinishScene()

Ends the scene currently being recorded, if any.

Called whenever what the following draws render into changes - a render-target switch, the frame's presentation, or a resource the open scene still references going away.

static const void* nCine::RHI::GXM::GxmDevice::GetQuadCornerStream()

Returns the static vertex stream feeding aQuadCorner for the 4-vertex sprite strip.

The corners are in the order of the single-quad TRIANGLE_STRIP draw - {(1,0), (1,1), (0,0), (0,1)} - which is what the Cg emitter's rewrite of the engine's gl_VertexID corner formula expects (see ShaderCompiler::VertexIdRewrite). Two floats per vertex.

static const void* nCine::RHI::GXM::GxmDevice::GetBatchedCornerStream()

Returns the static vertex stream feeding aQuadCorner + aInstanceIndex for batched sprites.

Six vertices per sprite (two triangles) carrying the batched corner order {(1,1), (0,1), (0,0), (0,0), (1,0), (1,1)} and the sprite's index within the batch, so a batched draw of 6 * n vertices reproduces the gl_VertexID / 6 instance lookup and the corner formula the emitter rewrote. Three floats per vertex; covers MaxBatchSize sprites.

static bool nCine::RHI::GXM::GxmDevice::CreateSwapchain(void* windowHandle, std::int32_t width, std::int32_t height, bool vsync)

Brings up the whole sceGxm session and the display queue.

Parameters
windowHandle Ignored (the Vita has one fixed display, so there is no window to attach to); accepted only to keep the uniform swap-chain contract of the other backends
width Ignored, the panel is always 960x544
height Ignored
vsync Whether PresentFrame() waits for the display swap to be picked up
Returns true if sceGxm, the context, the surfaces and the built-in shaders all came up

static std::int32_t nCine::RHI::GXM::GxmDevice::GetMaxTextureDimension() constexpr

Returns the largest supported 2D texture dimension.

4096 is the SGX543's limit; it only feeds the tileset chunking in ContentResolver and the texture-load assert, both of which the console's content stays well below.