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, const SDL_FColor *clearColor)
	Returns a populated SDL_GPUColorTargetInfo for color attachment index.
SDL_GPUDepthStencilTargetInfo	depthTargetInfo (const Framebuffer *self, SDL_GPULoadOp loadOp, SDL_GPUStoreOp storeOp, float clearDepth)
	Returns a populated SDL_GPUDepthStencilTargetInfo for this framebuffer's depth attachment.
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 *	resolveDepthTexture (const Framebuffer *self)
	Returns the single-sample, sampleable depth texture, to read scene depth (e.g. soft particles).
Class *	_Framebuffer (void)
	The Framebuffer archetype.

Data Fields
Object	object
	The superclass.
SDL_Size	size
	The framebuffer dimensions.
SDL_GPUSampleCount	sampleCount
	The MSAA sample count of all attachments.
Uint32	numColorTargets
	The number of color attachments; indices [0, numColorTargets) are valid.
SDL_GPUTextureFormat	colorFormats [GPU_MAX_COLOR_TARGETS]
	The color attachment texture formats, indices [0, numColorTargets).
Texture *	colorTextures [GPU_MAX_COLOR_TARGETS]
	The color attachment textures, indices [0, numColorTargets).
Texture *	resolveTextures [GPU_MAX_COLOR_TARGETS]
	The single-sample resolve targets, or all NULL unless sampleCount > SDL_GPU_SAMPLECOUNT_1.
SDL_GPUTextureFormat	depthFormat
	The depth attachment texture format, or 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 },
  .colorFormats = { SDL_GPU_TEXTUREFORMAT_R16G16B16A16_FLOAT },
  .numColorTargets = 1,
  .depthFormat = SDL_GPU_TEXTUREFORMAT_D32_FLOAT,
  .sampleCount = SDL_GPU_SAMPLECOUNT_1,
});
 
SDL_GPUColorTargetInfo color = $(fb, colorTargetInfo, 0,
  SDL_GPU_LOADOP_CLEAR, SDL_GPU_STOREOP_STORE,
  &(SDL_FColor) { 0, 0, 0, 1 });
 
SDL_GPUDepthStencilTargetInfo depth = $(fb, depthTargetInfo,
  SDL_GPU_LOADOP_CLEAR, SDL_GPU_STOREOP_DONT_CARE, 1.f);
 
RenderPass *pass = $(commands, beginRenderPass, &color, 1, &depth);
// ...
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,
		const SDL_FColor *	clearColor
	)

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.
clearColor	Clear color used when loadOp is SDL_GPU_LOADOP_CLEAR, or NULL for black.

Returns

A stack-allocated SDL_GPUColorTargetInfo.

depthTargetInfo()

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

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

Pass the result directly to CommandBuffer::beginRenderPass. asserts that depthTexture 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.
clearDepth	Clear depth value used when loadOp is SDL_GPU_LOADOP_CLEAR.

Returns

A stack-allocated SDL_GPUDepthStencilTargetInfo.

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.

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 resolveTextures[index] when multisampled, otherwise colorTextures[index].

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 resolveDepthTexture, 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.

Field Documentation

colorFormats

SDL_GPUTextureFormat Framebuffer::colorFormats[GPU_MAX_COLOR_TARGETS]

The color attachment texture formats, indices [0, numColorTargets).

colorTextures

Texture* Framebuffer::colorTextures[GPU_MAX_COLOR_TARGETS]

The color attachment textures, indices [0, numColorTargets).

Multisampled when sampleCount > SDL_GPU_SAMPLECOUNT_1; in that case sample/blit/present the corresponding resolveTextures entry, not these.

data

ident Framebuffer::data

User data.

depthFormat

SDL_GPUTextureFormat Framebuffer::depthFormat

The depth attachment texture format, or SDL_GPU_TEXTUREFORMAT_INVALID if none.

interface

FramebufferInterface* Framebuffer::interface

protected

The interface.

numColorTargets

Uint32 Framebuffer::numColorTargets

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

object

Object Framebuffer::object

The superclass.

resolveTextures

Texture* Framebuffer::resolveTextures[GPU_MAX_COLOR_TARGETS]

The single-sample resolve targets, or all NULL unless sampleCount > SDL_GPU_SAMPLECOUNT_1.

Render passes resolve colorTextures[i] into resolveTextures[i]; that is the texture to sample, blit, or present. See resolveColorTexture.

sampleCount

SDL_GPUSampleCount Framebuffer::sampleCount

The MSAA sample count of all attachments.

SDL_GPU_SAMPLECOUNT_1 for no multisampling. When greater, every color attachment and the depth attachment are multisampled (a render pass requires a single sample count across all attachments); each color attachment also gets a single-sample resolve target in resolveTextures.

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