fullscreen.h

#include <modkit/fullscreen.h>7 functions · 1 structs · 1 enums · 2 typedefs · 1 macros

Core fullscreen-pass API (unopinionated).

A fullscreen pass draws a single bufferless triangle (synthesized from gl_VertexID) covering the screen the workhorse of present, copy, and post-process passes. This module ships the built-in triangle vertex shader so callers never author one, plus a thin pass driver and a couple of universal, non-policy conveniences (blit, channel inspector). Opinionated effects (tonemap operators, blur kernels, bloom variants) are deliberately NOT here each has many valid implementations and belongs in an optional post-fx package built on top of this core, not in the framework core.

Functions

mk_fullscreen_bind_trianglefunction

bool mk_fullscreen_bind_triangle(mk_encoder_t encoder)

Bind a transient fullscreen triangle to an encoder.

Internal/power helper for fullscreen passes that submit manually. It avoids backend-specific fragility in vertex-count-only draws while remaining compatible with the built-in fullscreen vertex shader.

Parameter	Type	Description
encoder	mk_encoder_t	Value for encoder.

Returns True when the operation succeeds.

mk_fullscreen_blitfunction

void mk_fullscreen_blit(mk_texture_t src, mk_render_target_t target)

Present/copy src to target as a sampled fullscreen draw.

NOTE: this is a sampled blit (a shader reads src and writes the target), NOT a raw GPU copy. For exact copy semantics (matching format/size, no shader) use mk_encoder_blit instead.

Parameter	Type	Description
src	mk_texture_t	Source texture to sample.
target	mk_render_target_t	Destination; MK_RENDER_TARGET_INVALID => backbuffer.

mk_fullscreen_blit_shaderfunction

mk_shader_t mk_fullscreen_blit_shader(void)

Built-in fullscreen VS + built-in blit FS (samples s_tex at stage 0).

The program OWNS its s_tex sampler: retrieve it with mk_shader_uniform(shader, "s_tex"); do NOT destroy that uniform yourself (it lives for the program's lifetime). Destroy the program with mk_shader_destroy.

Returns Shader handle or MK_SHADER_INVALID on failure.

mk_fullscreen_debugfunction

void mk_fullscreen_debug(mk_texture_t src, mk_fullscreen_debug_mode_t mode, mk_render_target_t target)

Visualize one channel (or RGB) of src to target for debugging.

Parameter	Type	Description
src	mk_texture_t	Texture to inspect.
mode	mk_fullscreen_debug_mode_t	Which channel/view (mk_fullscreen_debug_mode_t).
target	mk_render_target_t	Destination; MK_RENDER_TARGET_INVALID => backbuffer.

mk_fullscreen_passfunction

void mk_fullscreen_pass(const mk_fullscreen_desc *desc)

Run a fullscreen pass: open a pass (optional clear/target), draw the bufferless fullscreen triangle (3 vertices, no vertex buffer), then end the pass.

No-op if desc is NULL or neither pipeline nor shader is valid (checked before any pass is opened).

Parameter	Type	Description
desc	const mk_fullscreen_desc *	Configuration descriptor.

mk_fullscreen_shaderfunction

mk_shader_t mk_fullscreen_shader(const void *fs_data, uint32_t fs_size)

Link the built-in fullscreen-triangle vertex shader with a USER fragment shader.

The fragment shader MUST declare $input v_texcoord0 (TEXCOORD0) so it links with the built-in VS by semantic. The caller is responsible for the fragment shader's uniforms: create them (mk_uniform_create) BEFORE calling this, because bgfx binds uniforms to a program at link time and modkit cannot infer a custom FS's uniforms. The returned program is owned by the caller (destroy with mk_shader_destroy).

Parameter	Type	Description
fs_data	const void *	Fragment shader binary.
fs_size	uint32_t	Fragment shader binary size in bytes.

Returns Shader handle or MK_SHADER_INVALID on failure.

mk_fullscreen_shutdownfunction

void mk_fullscreen_shutdown(void)

Perform the fullscreen shutdown operation.

Structs

mk_fullscreen_descstruct

Fullscreen pass descriptor.

Zero-init = sane defaults: backbuffer target, no clear, default fullscreen state (write RGBA, no depth test/write, no cull). Provide either pipeline (preferred) or the inline shader shortcut.

Field	Type	Description
pipeline	mk_pipeline_t	PSO (preferred).
shader	mk_shader_t	inline shortcut, used iff pipeline invalid
state	uint64_t	0 => MK_STATE_WRITE_RGB|MK_STATE_WRITE_A
blend_rgba	uint32_t	inline blend factor constant
name	const char *	pass debug name (optional)
target	mk_render_target_t	MK_RENDER_TARGET_INVALID => backbuffer.
clear_color	uint32_t	RGBA clear color (if clear_flags set).
clear_flags	uint16_t	0 => no clear; e.g.
textures	mk_tex_binding	The textures.
texture_count	uint8_t	The texture count.
uniforms	mk_uniform_binding	The uniforms.
uniform_count	uint8_t	The uniform count.

Enums

mk_fullscreen_debug_modeenum

Channel views for mk_fullscreen_debug.

Pure texture inspection only no renderer-specific normal/depth interpretation.

Value	Description
MK_FS_DEBUG_RGB	raw RGB
MK_FS_DEBUG_R	red as grayscale
MK_FS_DEBUG_G	green as grayscale
MK_FS_DEBUG_B	blue as grayscale
MK_FS_DEBUG_A	alpha as grayscale
MK_FS_DEBUG_LUMA	luminance

Typedefs

mk_fullscreen_debug_mode_ttypedef

typedef enum mk_fullscreen_debug_mode mk_fullscreen_debug_mode_t

Channel views for mk_fullscreen_debug.

Pure texture inspection only no renderer-specific normal/depth interpretation.

mk_fullscreen_desctypedef

typedef struct mk_fullscreen_desc mk_fullscreen_desc

Fullscreen pass descriptor.

Zero-init = sane defaults: backbuffer target, no clear, default fullscreen state (write RGBA, no depth test/write, no cull). Provide either pipeline (preferred) or the inline shader shortcut.

Macros

mk_fullscreen_shader_multidefine

mk_fullscreen_shader_multi(fs)

Convenience for multi-profile embedded fragment shaders (modkit_add_shaders_multi): mk_fullscreen_shader_multi(fs_invert).