CF_CanvasParams

Category: graphics
GitHub: cute_graphics.h

---

A texture the GPU can draw upon (with an optional depth/stencil texture).

Struct Members	Description
const char* name	The name of the canvas, for debug purposes.
union	The color target(s). target aliases targets[0], so single-target code reads and
writes exactly as before. For multiple render targets set target_count and fill
targets[1] through targets[target_count - 1] -- cf_canvas_defaults pre-fills every slot
with the same defaults, so typically only the pixel formats need adjusting. A fragment
shader writes them via layout (location = N) out. See CF_TextureParams.
int target_count	How many color targets this canvas has, from 1 to CF_MAX_CANVAS_TARGETS. Zero means
one, so zero-initialized params behave exactly as before this member existed. Multiple render
targets currently require sample_count of CF_SAMPLE_COUNT_1.
CF_Texture attach_target	Optional: render into one face/layer/slice of an existing cube, array, or 3D texture
instead of creating a color target. The texture needs CF_TEXTURE_USAGE_COLOR_TARGET_BIT.
The classic use is point-light shadows: make one cube texture, then six canvases attached to
its faces, and render the scene once per face. The canvas does not own the texture --
destroying the canvas leaves it alive, and cf_canvas_get_target returns it. Zero'd handle
(the default) creates an owned 2D target as usual.

   A DEPTH-format attach (needs [CF_TEXTURE_USAGE_DEPTH_STENCIL_TARGET_BIT](../../graphics/enum/cf_textureusagebits.md)) flips the meaning:
   the texture becomes the canvas's depth attachment and there is no color side at all -- a
   depth-only pass, pairing with `compare_enable` and `samplerCubeShadow`/`sampler2DShadow` for
   shadow maps. Note: cube-face DEPTH rendering currently only lands on the OpenGL ES backend
   and SDL_GPU's Vulkan/Metal drivers -- SDL_GPU's D3D12 driver creates only 2D depth views, so
   depth cube faces silently miss there (2D depth attaches work everywhere).

int attach_layer | Which face (0-5: +X, -X, +Y, -Y, +Z, -Z), array layer, or 3D slice of attach_target to render into.

   For a cube face rendered through a right-handed camera ([cf_look_at](../../math/function/cf_look_at.md)/[cf_perspective](../../math/function/cf_perspective.md),
   e.g. via `cute_draw3d.h`), mind the T axis: CF renders top-row-first (row 0 at clip
   y = +1), which is the opposite of the row a right-handed face camera's `up` vector
   would put there. Rendering as-is stores every face upside down; a `samplerCube` fetch
   then reads shadows/reflections from the mirrored elevation. Mirror clip-space y in the
   face projection to fix it (which reverses triangle winding, so flip cull mode too). See
   `samples/point_light.c`'s `face_projection`/`face_state` for the exact fix.

int attach_mip | Which mip level of attach_target to render into (default 0). The canvas takes the mip's dimensions, so cf_canvas_get_size and the viewport shrink accordingly. This is the render-into-mip primitive behind downsample chains (bloom: one canvas per mip, sample mip N-1 while rendering mip N) and IBL prefiltering (combine with attach_layer for one canvas per cube face per roughness mip). Composes with attach_layer; the texture needs allocate_mipmaps (see CF_TextureParams). bool depth_stencil_enable | Defaults to false. If true enables a depth-stencil buffer attachment. Required for any depth or stencil testing: without it the depth fields of CF_RenderState are silently ignored, which for 3d looks like the far side of a model drawing over the near side. CF_TextureParams depth_stencil_target | The texture used to store depth and stencil information when rendering to the canvas. See CF_TextureParams. CF_SampleCount sample_count | MSAA sample count; must be 1, 2, 4, or 8 (see CF_SampleCount). Defaults to 1 (no MSAA).

Remarks

The clear color settings are used when cf_apply_canvas is called. You can change the clear color by calling cf_clear_color. Make your own canvas whenever you want to draw to an off-screen buffer. Use cases include rendering at a fixed low resolution for a retro/pixel-art look (draw at e.g. 320x180, then scale up to the window with cf_draw_canvas), rendering reflections, advanced lighting techniques, or other kinds of multi-pass effects.

Related Pages

cf_clear_color
cf_canvas_defaults
cf_make_canvas
cf_destroy_canvas
cf_apply_canvas