view.h

#include <modkit/view.h>51 functions · 1 structs · 1 enums · 5 typedefs · 20 macros

View ID allocator and encoder API for render passes.

Views are "buckets" for draw/compute calls (render passes). View IDs range from 0-255. This module provides automatic allocation so you don't have to manually manage IDs. Views have these properties:Name (debug)Rect (viewport)ScissorClear (color/depth/stencil)Mode (sorting: Default, Sequential, DepthAscending, DepthDescending)FrameBuffer (render target)Transform (view/projection matrices) View state persists between frames unless explicitly reset.

Functions

mk_encoder_alloc_transformfunction

uint32_t mk_encoder_alloc_transform(mk_encoder_t enc, mk_transform_cache_t *transform, uint16_t num)

Allocate transform slots in cache via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
transform	mk_transform_cache_t *	Value for transform.
num	uint16_t	Value for num.

Returns The resulting value.

mk_encoder_beginfunction

mk_encoder_t mk_encoder_begin(bool force_new)

Begin encoding draw commands.

Parameter	Type	Description
force_new	bool	If true, creates new encoder even if one is cached

Returns Encoder handle for submitting draw commands

mk_encoder_blitfunction

void mk_encoder_blit(mk_encoder_t enc, mk_view_id_t view, mk_texture_t dst, uint8_t dst_mip, uint16_t dst_x, uint16_t dst_y, uint16_t dst_z, mk_texture_t src, uint8_t src_mip, uint16_t src_x, uint16_t src_y, uint16_t src_z, uint16_t width, uint16_t height, uint16_t depth)

Blit texture region via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
view	mk_view_id_t	Value for view.
dst	mk_texture_t	Value for dst.
dst_mip	uint8_t	Value for dst mip.
dst_x	uint16_t	Value for dst x.
dst_y	uint16_t	Value for dst y.
dst_z	uint16_t	Value for dst z.
src	mk_texture_t	Value for src.
src_mip	uint8_t	Value for src mip.
src_x	uint16_t	Value for src x.
src_y	uint16_t	Value for src y.
src_z	uint16_t	Value for src z.
width	uint16_t	Value for width.
height	uint16_t	Value for height.
depth	uint16_t	Value for depth.

mk_encoder_discardfunction

void mk_encoder_discard(mk_encoder_t enc, uint8_t flags)

Discard state via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Encoder receiving the discard command
flags	uint8_t	MK_DISCARD_* flags

mk_encoder_dispatchfunction

void mk_encoder_dispatch(mk_encoder_t enc, mk_view_id_t view, mk_shader_t shader, uint32_t num_x, uint32_t num_y, uint32_t num_z, uint8_t flags)

Dispatch compute shader via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Encoder
view	mk_view_id_t	View ID
shader	mk_shader_t	Compute shader program
num_x	uint32_t	Number of workgroups in X
num_y	uint32_t	Number of workgroups in Y
num_z	uint32_t	Number of workgroups in Z
flags	uint8_t	Discard flags

mk_encoder_endfunction

void mk_encoder_end(mk_encoder_t encoder)

End encoding and submit all queued commands.

Parameter	Type	Description
encoder	mk_encoder_t	Value for encoder.

mk_encoder_set_compute_dibuffunction

void mk_encoder_set_compute_dibuf(mk_encoder_t enc, uint8_t stage, mk_dibuf_t dibuf, mk_access_t access)

Set compute dynamic index buffer via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
stage	uint8_t	Value for stage.
dibuf	mk_dibuf_t	Value for dibuf.
access	mk_access_t	Value for access.

mk_encoder_set_compute_dvbuffunction

void mk_encoder_set_compute_dvbuf(mk_encoder_t enc, uint8_t stage, mk_dvbuf_t dvbuf, mk_access_t access)

Set compute dynamic vertex buffer via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
stage	uint8_t	Value for stage.
dvbuf	mk_dvbuf_t	Value for dvbuf.
access	mk_access_t	Value for access.

mk_encoder_set_compute_ibuffunction

void mk_encoder_set_compute_ibuf(mk_encoder_t enc, uint8_t stage, mk_ibuf_t ibuf, mk_access_t access)

Set compute index buffer via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
stage	uint8_t	Value for stage.
ibuf	mk_ibuf_t	Value for ibuf.
access	mk_access_t	Value for access.

mk_encoder_set_compute_vbuffunction

void mk_encoder_set_compute_vbuf(mk_encoder_t enc, uint8_t stage, mk_vbuf_t vbuf, mk_access_t access)

Set compute vertex buffer via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
stage	uint8_t	Value for stage.
vbuf	mk_vbuf_t	Value for vbuf.
access	mk_access_t	Value for access.

mk_encoder_set_dibuffunction

void mk_encoder_set_dibuf(mk_encoder_t enc, mk_dibuf_t dibuf, uint32_t first, uint32_t num)

Set dynamic index buffer via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
dibuf	mk_dibuf_t	Value for dibuf.
first	uint32_t	Value for first.
num	uint32_t	Value for num.

mk_encoder_set_dvbuffunction

void mk_encoder_set_dvbuf(mk_encoder_t enc, uint8_t stream, mk_dvbuf_t dvbuf, uint32_t start, uint32_t num)

Set dynamic vertex buffer via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
stream	uint8_t	Value for stream.
dvbuf	mk_dvbuf_t	Value for dvbuf.
start	uint32_t	Value for start.
num	uint32_t	Value for num.

mk_encoder_set_ibuffunction

void mk_encoder_set_ibuf(mk_encoder_t enc, mk_ibuf_t ibuf, uint32_t first, uint32_t num)

Set static index buffer via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
ibuf	mk_ibuf_t	Value for ibuf.
first	uint32_t	Value for first.
num	uint32_t	Value for num.

mk_encoder_set_imagefunction

void mk_encoder_set_image(mk_encoder_t enc, uint8_t stage, mk_texture_t texture, uint8_t mip, mk_access_t access, mk_texture_format_t format)

Set image for compute shader via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Encoder
stage	uint8_t	Binding stage (0-15)
texture	mk_texture_t	Texture to bind
mip	uint8_t	Mip level to access
access	mk_access_t	Access mode
format	mk_texture_format_t	Texture format (MK_TEXTURE_FORMAT_COUNT for auto)

mk_encoder_set_instancefunction

void mk_encoder_set_instance(mk_encoder_t enc, const mk_instance_buf_t *ibuf, uint32_t start, uint32_t num)

Set instance data buffer via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
ibuf	const mk_instance_buf_t *	Value for ibuf.
start	uint32_t	Value for start.
num	uint32_t	Value for num.

mk_encoder_set_instance_countfunction

void mk_encoder_set_instance_count(mk_encoder_t enc, uint32_t num)

Set instance count via encoder (for auto-instancing).

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
num	uint32_t	Value for num.

mk_encoder_set_instance_data_dvbuffunction

void mk_encoder_set_instance_data_dvbuf(mk_encoder_t enc, mk_dvbuf_t dvbuf, uint32_t start, uint32_t num)

Use a dynamic vertex buffer as the per-instance data source.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
dvbuf	mk_dvbuf_t	Value for dvbuf.
start	uint32_t	Value for start.
num	uint32_t	Value for num.

mk_encoder_set_instance_data_vbuffunction

void mk_encoder_set_instance_data_vbuf(mk_encoder_t enc, mk_vbuf_t vbuf, uint32_t start, uint32_t num)

Use a static vertex buffer as the per-instance data source (instead of a transient instance buffer).

start/num are in vertices.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
vbuf	mk_vbuf_t	Value for vbuf.
start	uint32_t	Value for start.
num	uint32_t	Value for num.

mk_encoder_set_markerfunction

void mk_encoder_set_marker(mk_encoder_t enc, const char *name)

Set debug marker via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
name	const char *	Stable name.

mk_encoder_set_scissorfunction

uint16_t mk_encoder_set_scissor(mk_encoder_t enc, uint16_t x, uint16_t y, uint16_t w, uint16_t h)

Set scissor rectangle via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
x	uint16_t	Value for x.
y	uint16_t	Value for y.
w	uint16_t	Value for w.
h	uint16_t	Value for h.

Returns The resulting value.

mk_encoder_set_scissor_cachedfunction

void mk_encoder_set_scissor_cached(mk_encoder_t enc, uint16_t cache)

Restore a cached scissor; UINT16_MAX disables per-draw scissor.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
cache	uint16_t	Value for cache.

mk_encoder_set_statefunction

void mk_encoder_set_state(mk_encoder_t enc, uint64_t state, uint32_t rgba)

Set render state via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
state	uint64_t	Value for state.
rgba	uint32_t	Value for RGBA.

mk_encoder_set_stencilfunction

void mk_encoder_set_stencil(mk_encoder_t enc, uint32_t front, uint32_t back)

Set stencil state via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
front	uint32_t	Value for front.
back	uint32_t	Value for back.

mk_encoder_set_texturefunction

void mk_encoder_set_texture(mk_encoder_t enc, uint8_t stage, mk_uniform_t sampler, mk_texture_t texture, uint32_t flags)

Set texture via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Encoder
stage	uint8_t	Texture stage (0-15)
sampler	mk_uniform_t	Sampler uniform (mk_uniform_t)
texture	mk_texture_t	Texture handle
flags	uint32_t	Sampler flags (UINT32_MAX for default)

mk_encoder_set_transformfunction

uint32_t mk_encoder_set_transform(mk_encoder_t enc, const void *mtx, uint16_t num)

Set model transform matrix via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Encoder
mtx	const void *	Pointer to 4x4 matrix (or array of matrices)
num	uint16_t	Number of matrices (1 for single transform)

Returns Transform cache index for use with mk_encoder_set_transform_cached

mk_encoder_set_transform_cachedfunction

void mk_encoder_set_transform_cached(mk_encoder_t enc, uint32_t cache, uint16_t num)

Set transform from cache via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
cache	uint32_t	Value for cache.
num	uint16_t	Value for num.

mk_encoder_set_uniformfunction

void mk_encoder_set_uniform(mk_encoder_t enc, mk_uniform_t uniform, const void *value, uint16_t num)

Set uniform value via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Encoder
uniform	mk_uniform_t	Uniform handle
value	const void *	Pointer to uniform data
num	uint16_t	Number of elements (for arrays, 1 for single value)

mk_encoder_set_vbuffunction

void mk_encoder_set_vbuf(mk_encoder_t enc, uint8_t stream, mk_vbuf_t vbuf, uint32_t start, uint32_t num)

Set static vertex buffer via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
stream	uint8_t	Value for stream.
vbuf	mk_vbuf_t	Value for vbuf.
start	uint32_t	Value for start.
num	uint32_t	Value for num.

mk_encoder_set_vertex_countfunction

void mk_encoder_set_vertex_count(mk_encoder_t enc, uint32_t num)

Submit a draw using only a vertex count, with no vertex buffer bound (the vertex shader synthesizes positions from gl_VertexID).

Ideal for fullscreen triangle/quad passes. See also mk_draw_desc.vertex_count.

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
num	uint32_t	Value for num.

mk_encoder_submitfunction

void mk_encoder_submit(mk_encoder_t enc, mk_view_id_t id, mk_shader_t shader, uint32_t depth, uint8_t flags)

Set transient vertex/index buffer via encoder.

Requires modkit.h for mk_transient_vbuf_t / mk_transient_ibuf_t types. Submit draw call via encoder.

Parameter	Type	Description
enc	mk_encoder_t	Encoder
id	mk_view_id_t	View ID
shader	mk_shader_t	Shader (mk_shader_t)
depth	uint32_t	Depth for sorting
flags	uint8_t	Discard flags (MK_DISCARD_*)

mk_encoder_touchfunction

void mk_encoder_touch(mk_encoder_t enc, mk_view_id_t id)

Touch view via encoder (ensures view is processed).

Parameter	Type	Description
enc	mk_encoder_t	Value for enc.
id	mk_view_id_t	Value for ID.

mk_set_palette_colorfunction

void mk_set_palette_color(uint8_t index, const float rgba[4])

Set a clear-palette color entry (index 0..255).

View clear flags can reference palette indices for multi-render-target clears.

Parameter	Type	Description
index	uint8_t	Zero-based index.
rgba	const float	Value for RGBA.

mk_view_allocfunction

mk_view_id_t mk_view_alloc(const char *name)

Allocate a view ID.

Parameter	Type	Description
name	const char *	Debug name (can be NULL)

Returns Allocated view ID, or MK_VIEW_INVALID if exhausted

mk_view_clearfunction

void mk_view_clear(mk_view_id_t id, uint16_t flags, uint32_t rgba, float depth, uint8_t stencil)

Set view clear state.

Parameter	Type	Description
id	mk_view_id_t	Value for ID.
flags	uint16_t	Value for flags.
rgba	uint32_t	Value for RGBA.
depth	float	Value for depth.
stencil	uint8_t	Value for stencil.

mk_view_countfunction

uint16_t mk_view_count(void)

Get count of allocated views.

Returns The resulting value.

mk_view_frame_bufferfunction

void mk_view_frame_buffer(mk_view_id_t id, mk_framebuf_t fb)

Bind a framebuffer to a view (NULL framebuffer = backbuffer).

Used by subsystems that allocate auxiliary views to mirror the caller's render target (e.g. model.c transmission framebuffer-capture path).

Parameter	Type	Description
id	mk_view_id_t	Value for ID.
fb	mk_framebuf_t	Value for fb.

mk_view_freefunction

void mk_view_free(mk_view_id_t id)

Release a view ID back to the pool.

Also resets any associated view state.

Parameter	Type	Description
id	mk_view_id_t	Value for ID.

mk_view_initfunction

void mk_view_init(void)

Initialize the view allocator.

Called automatically by mk_init().

mk_view_is_allocatedfunction

bool mk_view_is_allocated(mk_view_id_t id)

Check if a view ID is currently allocated.

Parameter	Type	Description
id	mk_view_id_t	Value for ID.

Returns True when the condition holds.

mk_view_modefunction

void mk_view_mode(mk_view_id_t id, mk_view_mode_t mode)

Set view rendering mode.

Parameter	Type	Description
id	mk_view_id_t	View ID
mode	mk_view_mode_t	View sort mode (MK_VIEW_MODE_*)

mk_view_namefunction

void mk_view_name(mk_view_id_t id, const char *name)

Set view name for debugging.

Parameter	Type	Description
id	mk_view_id_t	Value for ID.
name	const char *	Stable name.

mk_view_rectfunction

void mk_view_rect(mk_view_id_t id, uint16_t x, uint16_t y, uint16_t w, uint16_t h)

Set view rectangle (viewport).

Parameter	Type	Description
id	mk_view_id_t	Value for ID.
x	uint16_t	Value for x.
y	uint16_t	Value for y.
w	uint16_t	Value for w.
h	uint16_t	Value for h.

mk_view_resetfunction

void mk_view_reset(mk_view_id_t id)

Reset a view's settings to defaults without releasing the ID (rect, clear, transform, scissor, framebuffer, etc.).

Use to recycle a still-allocated view.

Parameter	Type	Description
id	mk_view_id_t	Value for ID.

mk_view_set_orderfunction

void mk_view_set_order(uint16_t first, uint16_t num, const mk_view_id_t *order)

Set explicit view ordering for the given range.

bgfx executes views in ID order by default; this lets callers force a specific order even when view IDs are non-contiguous (e.g. when allocated dynamically by multiple subsystems).

Parameter	Type	Description
first	uint16_t	First view in the range
num	uint16_t	Number of views in order
order	const mk_view_id_t *	Array of view IDs in desired execution order

mk_view_set_scissorfunction

void mk_view_set_scissor(mk_view_id_t id, uint16_t x, uint16_t y, uint16_t w, uint16_t h)

Set a view-wide scissor rectangle (clips all draws in the view).

w or h of 0 disables scissor. This is the view-level counterpart to the per-draw mk_encoder_set_scissor.

Parameter	Type	Description
id	mk_view_id_t	Value for ID.
x	uint16_t	Value for x.
y	uint16_t	Value for y.
w	uint16_t	Value for w.
h	uint16_t	Value for h.

mk_view_setupfunction

void mk_view_setup(mk_view_id_t id, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t clear_flags, uint32_t clear_rgba, float clear_depth, uint8_t clear_stencil, const void *view_mtx, const void *proj_mtx)

Configure a view with common settings.

Pass NULL for any matrix to use identity.

Parameter	Type	Description
id	mk_view_id_t	Value for ID.
x	uint16_t	Value for x.
y	uint16_t	Value for y.
width	uint16_t	Value for width.
height	uint16_t	Value for height.
clear_flags	uint16_t	Value for clear flags.
clear_rgba	uint32_t	Value for clear RGBA.
clear_depth	float	Value for clear depth.
clear_stencil	uint8_t	Value for clear stencil.
view_mtx	const void *	Value for view mtx.
proj_mtx	const void *	Value for proj mtx.

mk_view_setup_simplefunction

void mk_view_setup_simple(mk_view_id_t id, uint16_t width, uint16_t height, uint32_t clear_rgba)

Simple view setup for common case: full viewport, clear color+depth.

Parameter	Type	Description
id	mk_view_id_t	Value for ID.
width	uint16_t	Value for width.
height	uint16_t	Value for height.
clear_rgba	uint32_t	Value for clear RGBA.

mk_view_shading_ratefunction

void mk_view_shading_rate(mk_view_id_t id, mk_shading_rate_t rate)

Set the variable-rate shading rate for a view.

Requires GPU/back-end support.

Parameter	Type	Description
id	mk_view_id_t	Value for ID.
rate	mk_shading_rate_t	Value for rate.

mk_view_shutdownfunction

void mk_view_shutdown(void)

Shutdown the view allocator.

Called automatically by mk_shutdown().

mk_view_touchfunction

void mk_view_touch(mk_view_id_t id)

Touch view to ensure it's processed even without draw calls.

Parameter	Type	Description
id	mk_view_id_t	Value for ID.

mk_view_transformfunction

void mk_view_transform(mk_view_id_t id, const void *view_mtx, const void *proj_mtx)

Set view and projection matrices.

Pass NULL for identity matrix.

Parameter	Type	Description
id	mk_view_id_t	Value for ID.
view_mtx	const void *	Value for view mtx.
proj_mtx	const void *	Value for proj mtx.

Structs

mk_transform_cachestruct

Transform cache allocation result.

Field	Type	Description
data	float *	Pointer to first 4x4 matrix.
num	uint16_t	Number of matrices.

Enums

mk_accessenum

Buffer/image access mode for compute shaders.

Value	Description
MK_ACCESS_READ	Read-only access.
MK_ACCESS_WRITE	Write-only access.
MK_ACCESS_READWRITE	Read-write access.

Typedefs

mk_access_ttypedef

typedef enum mk_access mk_access_t

Buffer/image access mode for compute shaders.

mk_encoder_ttypedef

typedef struct mk_encoder* mk_encoder_t

Opaque encoder handle for submitting draw commands.

mk_transform_cache_ttypedef

typedef struct mk_transform_cache mk_transform_cache_t

Transform cache allocation result.

mk_view_id_ttypedef

typedef uint16_t mk_view_id_t

View ID type.

Views are render passes / buckets for draw calls.

mk_view_ttypedef

typedef mk_view_id_t mk_view_t

Type used for view.

Macros

MK_CLEAR_COLORdefine

MK_CLEAR_COLOR

Constant for clear color.

MK_CLEAR_DEPTHdefine

MK_CLEAR_DEPTH

Constant for clear depth.

MK_CLEAR_DISCARD_COLOR_0define

MK_CLEAR_DISCARD_COLOR_0

Constant for clear discard color 0.

MK_CLEAR_DISCARD_COLOR_1define

MK_CLEAR_DISCARD_COLOR_1

Constant for clear discard color 1.

MK_CLEAR_DISCARD_COLOR_2define

MK_CLEAR_DISCARD_COLOR_2

Constant for clear discard color 2.

MK_CLEAR_DISCARD_COLOR_3define

MK_CLEAR_DISCARD_COLOR_3

Constant for clear discard color 3.

MK_CLEAR_DISCARD_COLOR_4define

MK_CLEAR_DISCARD_COLOR_4

Constant for clear discard color 4.

MK_CLEAR_DISCARD_COLOR_5define

MK_CLEAR_DISCARD_COLOR_5

Constant for clear discard color 5.

MK_CLEAR_DISCARD_COLOR_6define

MK_CLEAR_DISCARD_COLOR_6

Constant for clear discard color 6.

MK_CLEAR_DISCARD_COLOR_7define

MK_CLEAR_DISCARD_COLOR_7

Constant for clear discard color 7.

MK_CLEAR_DISCARD_COLOR_MASKdefine

MK_CLEAR_DISCARD_COLOR_MASK

Constant for clear discard color mask.

MK_CLEAR_DISCARD_DEPTHdefine

MK_CLEAR_DISCARD_DEPTH

Constant for clear discard depth.

MK_CLEAR_DISCARD_MASKdefine

MK_CLEAR_DISCARD_MASK

Constant for clear discard mask.

MK_CLEAR_DISCARD_STENCILdefine

MK_CLEAR_DISCARD_STENCIL

Constant for clear discard stencil.

MK_CLEAR_NONEdefine

MK_CLEAR_NONE

Constant for clear none.

MK_CLEAR_STENCILdefine

MK_CLEAR_STENCIL

Constant for clear stencil.

MK_VIEW_INVALIDdefine

MK_VIEW_INVALID

Invalid sentinel for view.

MK_VIEW_MAXdefine

MK_VIEW_MAX

Maximum supported view max.

MODKIT_CONFIG_MAX_ENCODERSdefine

MODKIT_CONFIG_MAX_ENCODERS

Maximum supported modkit config encoders.

MODKIT_CONFIG_MAX_VIEWSdefine

MODKIT_CONFIG_MAX_VIEWS

Maximum supported modkit config views.