Framebuffer Struct Reference

An off-screen render target grouping a color and/or depth texture. More...

#include <Framebuffer.h>

Inheritance diagram for Framebuffer:

Public Member Functions
SDL_GPUColorTargetInfo	colorTargetInfo (const Framebuffer *self, Uint32 index, SDL_GPULoadOp loadOp, SDL_GPUStoreOp storeOp)
	Returns a populated SDL_GPUColorTargetInfo for color attachment index.
SDL_GPUDepthStencilTargetInfo	depthTargetInfo (const Framebuffer *self, SDL_GPULoadOp loadOp, SDL_GPUStoreOp storeOp)
	Returns a populated SDL_GPUDepthStencilTargetInfo for this framebuffer's depth attachment.
void	pipelineTargetInfo (const Framebuffer *self, const SDL_GPUColorTargetBlendState *blendStates, SDL_GPUColorTargetDescription *descriptions, SDL_GPUGraphicsPipelineTargetInfo *targetInfo)
	Populates descriptions and targetInfo for a GraphicsPipeline that targets this Framebuffer.
Framebuffer *	initWithDevice (Framebuffer *self, RenderDevice *device, const GPU_FramebufferCreateInfo *info)
	Initializes this Framebuffer and allocates its GPU textures.
bool	resize (Framebuffer *self, const SDL_Size *size)
	Releases the existing GPU textures and recreates them at size.
Texture *	resolveColorTexture (const Framebuffer *self, Uint32 index)
	Returns the single-sample, sampleable color texture for attachment index, to sample, blit, or present.
Texture *	previousColorTexture (const Framebuffer *self, Uint32 index)
	Returns the single-sample, sampleable color texture attachment index held last frame.
Texture *	resolveDepthTexture (const Framebuffer *self)
	Returns the single-sample, sampleable depth texture, to read scene depth (e.g. soft particles).
void	swap (Framebuffer *self)
	Advances the frame parity used by double-buffered attachments.
Class *	_Framebuffer (void)
	The Framebuffer archetype.

Data Fields
Object	object
	The superclass.
RenderDevice *	device
	The owning RenderDevice, used for texture allocation and dealloc.
SDL_Size	size
	The framebuffer dimensions.
SDL_GPUSampleCount	sampleCount
	The MSAA sample count of all color and depth attachments.
GPU_FramebufferAttachment	colorAttachments [GPU_MAX_COLOR_TARGETS]
	The color attachments, indices [0, numColorTargets).
Uint32	numColorAttachments
	The number of color attachments; indices [0, numColorTargets) are valid.
GPU_FramebufferAttachment	depthAttachment
	The depth attachment, or format SDL_GPU_TEXTUREFORMAT_INVALID if none.
ident	data
	User data.

Protected Attributes
FramebufferInterface *	interface
	The interface.

Detailed Description

An off-screen render target grouping a color and/or depth texture.

Framebuffer owns a pair of SDL_GPUTexture objects (color and/or depth) and provides helpers that produce the SDL_GPUColorTargetInfo and SDL_GPUDepthStencilTargetInfo values required by CommandBuffer::beginRenderPass.

Use SDL_GPU_TEXTUREFORMAT_INVALID for either format to omit that attachment. Call resize whenever the window dimensions change; it releases the existing textures and recreates them at the new size.

Framebuffer *fb = $(renderDevice, createFramebuffer, &(GPU_FramebufferCreateInfo) {
  .size = { 1920, 1080 },
  .colorAttachments = {
    { .format = SDL_GPU_TEXTUREFORMAT_R16G16B16A16_FLOAT, .clearColor = { 0.f, 0.f, 0.f, 1.f } },
  },
  .numColorTargets = 1,
  .depthAttachment = { .format = SDL_GPU_TEXTUREFORMAT_D32_FLOAT, .clearDepth = 1.f },
  .sampleCount = SDL_GPU_SAMPLECOUNT_1,
});
 
// Renders into all of fb's targets, clearing to their own clear color/depth.
RenderPass *pass = $(commands, beginRenderPassWithFramebuffer, fb,
  SDL_GPU_LOADOP_CLEAR, SDL_GPU_STOREOP_STORE);
// ...
release(pass);
release(fb);

Member Function Documentation

_Framebuffer()

Class * _Framebuffer

(

void

)

The Framebuffer archetype.

Returns

The Framebuffer Class.

colorTargetInfo()

SDL_GPUColorTargetInfo colorTargetInfo	(	const Framebuffer *	self,
		Uint32	index,
		SDL_GPULoadOp	loadOp,
		SDL_GPUStoreOp	storeOp
	)

Returns a populated SDL_GPUColorTargetInfo for color attachment index.

Assemble an array of these (one per color target) and pass it to CommandBuffer::beginRenderPass. When multisampled, the resolve target and a RESOLVE_AND_STORE store op are wired in automatically. asserts index is valid.

Parameters

self	The Framebuffer.
index	The color attachment index, in [0, numColorTargets).
loadOp	Load operation at the start of the pass.
storeOp	Store operation at the end of the pass.

Returns

A stack-allocated SDL_GPUColorTargetInfo, cleared to the attachment's own clearColor when loadOp is SDL_GPU_LOADOP_CLEAR.

depthTargetInfo()

SDL_GPUDepthStencilTargetInfo depthTargetInfo	(	const Framebuffer *	self,
		SDL_GPULoadOp	loadOp,
		SDL_GPUStoreOp	storeOp
	)

Returns a populated SDL_GPUDepthStencilTargetInfo for this framebuffer's depth attachment.

Pass the result directly to CommandBuffer::beginRenderPass. asserts that the depth attachment's texture is non-NULL.

Parameters

self	The Framebuffer.
loadOp	Load operation at the start of the pass.
storeOp	Store operation at the end of the pass.

Returns

A stack-allocated SDL_GPUDepthStencilTargetInfo, cleared to the attachment's own clearDepth when loadOp is SDL_GPU_LOADOP_CLEAR.

initWithDevice()

Framebuffer * initWithDevice	(	Framebuffer *	self,
		RenderDevice *	device,
		const GPU_FramebufferCreateInfo *	info
	)

Initializes this Framebuffer and allocates its GPU textures.

Parameters

self	The Framebuffer.
device	The RenderDevice used to allocate and release textures.
info	Framebuffer creation parameters (size, formats, sample count).

Returns

The initialized Framebuffer, or NULL on failure.

pipelineTargetInfo()

void pipelineTargetInfo	(	const Framebuffer *	self,
		const SDL_GPUColorTargetBlendState *	blendStates,
		SDL_GPUColorTargetDescription *	descriptions,
		SDL_GPUGraphicsPipelineTargetInfo *	targetInfo
	)

Populates descriptions and targetInfo for a GraphicsPipeline that targets this Framebuffer.

Pass one blend state per color attachment in blendStates (see GraphicsPipelinePresets), and caller-owned storage for descriptions with capacity numColorAttachments. The resulting targetInfo references descriptions, so descriptions must remain valid for as long as targetInfo (and any SDL_GPUGraphicsPipelineCreateInfo built from it) is in use.

Parameters

self	The Framebuffer.
blendStates	One blend state per color attachment, [0, numColorAttachments).
descriptions	Output storage for numColorAttachments color target descriptions.
targetInfo	Output: populated with descriptions and this Framebuffer's depth format.

previousColorTexture()

Texture * previousColorTexture	(	const Framebuffer *	self,
		Uint32	index
	)

Returns the single-sample, sampleable color texture attachment index held last frame.

Only valid for a double-buffered attachment (doubleBuffered true); asserts otherwise. Since this slot was not written this frame, it may be safely sampled within the same render pass that is concurrently writing resolveColorTexture's slot – e.g. soft particles sampling last frame's depth copy while the current frame's opaque geometry writes this frame's copy, all within one render pass, with no same-frame write-then-read hazard.

Parameters

self	The Framebuffer.
index	The color attachment index, in [0, numColorTargets).

Returns

The previous frame's resolved color texture.

resize()

bool resize	(	Framebuffer *	self,
		const SDL_Size *	size
	)

Releases the existing GPU textures and recreates them at size.

Call this when the window is resized. Returns false if size matches the current size and no reallocation is needed.

Parameters

self	The Framebuffer.
size	The new framebuffer dimensions.

Returns

true if textures were reallocated; false if the size was unchanged.

resolveColorTexture()

Texture * resolveColorTexture	(	const Framebuffer *	self,
		Uint32	index
	)

Returns the single-sample, sampleable color texture for attachment index, to sample, blit, or present.

Returns the current frame's resolved texture: the multisampled resolve target when the Framebuffer is multisampled, otherwise the attachment's own texture. For a double-buffered attachment, this is the slot being written this frame; see previousColorTexture for the other.

Parameters

self	The Framebuffer.
index	The color attachment index, in [0, numColorTargets).

Returns

The resolved color texture, or NULL if index has no attachment.

resolveDepthTexture()

Texture * resolveDepthTexture

(

const Framebuffer *

self

)

Returns the single-sample, sampleable depth texture, to read scene depth (e.g. soft particles).

Single-sample: the depth attachment itself (created with SAMPLER). Multisampled: the separate resolve texture, which must first be populated by a resolve pass (SDL has no depth store-op resolve). Returns NULL if the framebuffer has no depth attachment.

Parameters

self	The Framebuffer.

Returns

The sampleable depth texture, or NULL if there is no depth attachment.

swap()

void swap

(

Framebuffer *

self

)

Advances the frame parity used by double-buffered attachments.

Call this once per frame, after any double-buffered attachment has been written for the frame – e.g. at the end of the frame. Toggles which physical slot colorTargetInfo/resolveColorTexture write/read as "current" for each doubleBuffered attachment; the other slot becomes previousColorTexture.

Parameters

self	The Framebuffer.

Field Documentation

colorAttachments

GPU_FramebufferAttachment Framebuffer::colorAttachments[GPU_MAX_COLOR_TARGETS]

The color attachments, indices [0, numColorTargets).

data

ident Framebuffer::data

User data.

depthAttachment

GPU_FramebufferAttachment Framebuffer::depthAttachment

The depth attachment, or format SDL_GPU_TEXTUREFORMAT_INVALID if none.

device

RenderDevice* Framebuffer::device

The owning RenderDevice, used for texture allocation and dealloc.

interface

FramebufferInterface* Framebuffer::interface

protected

The interface.

numColorAttachments

Uint32 Framebuffer::numColorAttachments

The number of color attachments; indices [0, numColorTargets) are valid.

object

Object Framebuffer::object

The superclass.

sampleCount

SDL_GPUSampleCount Framebuffer::sampleCount

The MSAA sample count of all color and depth attachments.

size

SDL_Size Framebuffer::size

The framebuffer dimensions.

---

The documentation for this struct was generated from the following files:

• Sources/ObjectivelyGPU/Framebuffer.h
• Sources/ObjectivelyGPU/Framebuffer.c