Gx2Device class
#include <nCine/Graphics/RHI/GX2/Gx2Device.h>
Pipeline-state and draw-call facade of the GX2 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 backend's side of the GX2 session: its context state, the intermediate screen colour buffer and the present.
GX2 itself belongs to SDL. wiiu-sdl2's video driver calls GX2Init(), drives ProcUI, owns the TV and GamePad scan buffers and frees its MEM1 heap whenever the application goes to the background. The window backend keeps SDL's video subsystem and its window (for input and the ProcUI events) but creates no SDL_Renderer, so nothing else submits GX2 work. This device sets up its own GX2ContextState with shadowing enabled and renders with that.
"Screen" is an intermediate colour buffer the size of the window (the drawable size, see GetScreenWidth()). PresentFrame() copies it into the TV and GamePad scan buffers with GX2CopyColorBufferToScanBuffer(), which also scales it to each display's own resolution.
Background. Between EnterBackground() and EnterForeground() (the SDL_APP_WILLENTERBACKGROUND / SDL_APP_DIDENTERFOREGROUND events) nothing is submitted: clears, draws and presents return immediately, because SDL is about to release the foreground and its scan buffers and destroy its MEM1 heap. Before that, every block of this backend in MEM1 (the screen buffer and the render targets that asked for it, see Gx2Memory) is freed; when the application comes back the screen buffer is allocated again, the render targets on their next use, and the context state is made current again. Everything in MEM2 survives.
Draws. A draw binds the program's vertex, pixel and fetch shaders, fills the stages' loose-uniform blocks and copies the ranges the pipeline bound for the explicit blocks into a uniform ring (AllocateUniformData()), binds the textures to the units the pixel shader samples and one attribute buffer per engine attribute slot.
Uniform blocks are little endian. The GPU byte-swaps vertex attributes (GX2_ENDIAN_SWAP_DEFAULT) but reads uniform blocks as they are, so every block is copied into the ring with its 32-bit words swapped. Writing them in place in the engine's buffers is not safe, because a range may be flushed more than once.
The CPU runs ahead of the GPU. GX2 does not rename buffers, so nothing the GPU may still read is written by the CPU before the GPU is done with it. The device numbers the command batches it submits (GetUseToken()): the batch being recorded is flushed with GX2Flush() at the present (or when something has to wait for it), and the GX2 timestamp of that submission (GX2GetLastSubmittedTimeStamp()) is kept per batch, so a token is retired once GX2GetRetiredTimeStamp() has reached it. On top of that:
- the streaming vertex and index buffers are RenderBuffersManager's persistently mapped section ring (three sections), whose fences are such tokens (InsertFence(), ClientWaitFence());
- the uniform ring is cut into chunks, each remembering the batch that last read it, and a chunk is waited for before it is reused (AllocateUniformData());
- every texture and vertex/index buffer a draw reads is stamped with the token of that draw, and a CPU write to one that is still in use either moves it to a fresh block (when the whole store is replaced: the old block is retired) or waits for the token;
- blocks of destroyed or reallocated resources are freed only when their token has retired (RetireBlock()). The present submits the frame's draws first and then waits for the previous swap to flip before it records the scan copies (WaitForPreviousFlip()): the GPU draws one frame while the CPU records the next, and the CPU stays at most about a frame ahead of the scan-out.
Public types
- struct ScissorState
- struct BlendingState
- struct DepthTestState
- struct CullFaceState
Public static variables
-
static std::
uint32_t MaxBatchSize constexpr - Largest batch a batched sprite shader can address.
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
- Returns a fence for everything recorded so far: the token of the open batch (see GetUseToken()).
- static void DeleteFence(FenceHandle& fence)
-
static auto ClientWaitFence(FenceHandle fence,
std::
uint64_t timeoutNs) -> bool - static void SetupInitialState()
- static void BindProgram(Gx2ShaderProgram* program)
- Records the currently bound shader program.
- static auto CurrentProgram() -> Gx2ShaderProgram*
- Returns the currently bound shader program.
-
static void BindTexture(std::
uint32_t unit, const Gx2Texture* texture) - Records the texture bound to a texture unit.
- static void UnbindTexture(const Gx2Texture* texture)
- Clears a texture from every unit it is bound to (called from ~Gx2Texture to avoid a dangling pointer).
-
static auto GetBoundTexture(std::
uint32_t unit) -> const Gx2Texture* - 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 Gx2RenderTarget* renderTarget)
- Clears a render target from the device if it is the current one (called from ~Gx2RenderTarget).
- static void SetRenderTarget(Gx2RenderTarget* renderTarget)
- Records the current draw render target (its bound colour attachment receives the pixels).
- static void OnProgramDestroyed(const Gx2ShaderProgram* program)
- Clears a destroyed program from the device's current-program tracking (called from ~Gx2ShaderProgram).
- static void OnProgramBinariesReleased(const Gx2ShaderProgram* program)
- Makes the next draw with
programbind its shaders again, because its binaries were released. - static void Finish()
- Blocks until the GPU has executed everything submitted so far (
GX2DrawDone()). -
static auto GetUseToken() -> std::
uint32_t - Returns the token of the command batch being recorded A resource stores it when a draw reads it; the token retires once the GPU has executed the batch. Tokens are never 0, so 0 means "never used".
-
static auto IsUseRetired(std::
uint32_t token) -> bool - Whether the GPU has finished the batch of
token(without waiting; an unsubmitted batch is not). -
static auto WaitForUse(std::
uint32_t token) -> bool - Waits until the GPU has finished the batch of
token, submitting it first if it is still open. -
static void RetireBlock(Gx2Memory::
Block& block) - Holds
blockuntil the frames that may still reference it are done, then frees it. - static auto CanAllocMem1() -> bool
- Whether MEM1 may be allocated right now: only in the foreground, while SDL's MEM1 heap exists (see Gx2Memory).
-
static auto GetFrameCounter() -> std::
uint32_t - Monotonic count of presented frames.
-
static auto CreateSwapchain(void* windowHandle,
std::
int32_t width, std:: int32_t height, bool vsync) -> bool - Sets up the backend's GX2 context state and the screen colour buffer.
- static void DestroySwapchain()
- Waits for the GPU, then releases everything CreateSwapchain() created.
-
static void ResizeSwapchain(std::
int32_t width, std:: int32_t height) - No-op: the screen colour buffer keeps the window size, which does not change on the console.
- static void PresentFrame()
- Copies the screen colour buffer to the TV and GamePad scan buffers and queues the swap.
- static void BeginGpuTiming()
- No-op.
- static void EndGpuTiming()
- No-op.
- static void EnterBackground()
- Stops all GPU submission (
SDL_APP_WILLENTERBACKGROUND), after letting the GPU finish. - static void EnterForeground()
- Resumes GPU submission (
SDL_APP_DIDENTERFOREGROUND). -
static auto GetScreenWidth() -> std::
int32_t - Width of the screen colour buffer, which is the drawable size the window backend reports.
-
static auto GetScreenHeight() -> std::
int32_t - Height of the screen colour buffer.
-
static auto GetDisplayWidth() -> std::
int32_t - Same as GetScreenWidth(); the TV resolution itself is SDL's business.
-
static auto GetDisplayHeight() -> std::
int32_t - Same as GetScreenHeight().
-
static auto GetMaxTextureDimension() -> std::
int32_t constexpr - Largest supported 2D texture dimension.
-
static auto GetUniformBufferOffsetAlignment() -> std::
int32_t constexpr - Byte alignment the engine suballocates bound uniform ranges with (
GX2_UNIFORM_BLOCK_ALIGNMENT). -
static auto GetMaxUniformBlockSize() -> std::
int32_t constexpr - Byte budget of one uniform block.
Constructors, destructors, conversion operators
- Gx2Device() deleted
- ~Gx2Device() deleted
Function documentation
static void nCine:: RHI:: GX2:: Gx2Device:: RetireBlock(Gx2Memory:: Block& block)
Holds block until the frames that may still reference it are done, then frees it.
The GPU runs behind the CPU, so memory freed the moment a resource is destroyed may still be read by commands already queued. A retired block is freed once the batch that was open when it was retired has retired (checked at every present).
static bool nCine:: RHI:: GX2:: Gx2Device:: CreateSwapchain(void* windowHandle,
std:: int32_t width,
std:: int32_t height,
bool vsync)
Sets up the backend's GX2 context state and the screen colour buffer.
| Parameters | |
|---|---|
| windowHandle | Ignored, there is one TV and one GamePad |
| width | Width of the screen colour buffer (the window's) |
| height | Height of the screen colour buffer |
| vsync | Whether the present waits for vertical blank |
SDL's video driver must already be initialised (it owns GX2Init() and the scan buffers).
Variable documentation
static std:: uint32_t nCine:: RHI:: GX2:: Gx2Device:: MaxBatchSize constexpr
Largest batch a batched sprite shader can address.
GX2 uniform blocks are limited to 64 KB (GetMaxUniformBlockSize()), and the sprite instance stride is 112 bytes, so 585 instances fit; the generated batched shaders are compiled with the same BATCH_SIZE.