camera2d.h

#include <modkit/camera2d.h>19 functions · 2 structs · 1 enums · 3 typedefs

Y-down 2D camera and virtual-resolution helpers.

Functions

mk_camera2d_begin_canvasfunction

bool mk_camera2d_begin_canvas(const mk_camera2d *camera, mk_canvas_t canvas)

Push a camera transform and viewport clip onto a Canvas.

Parameter	Type	Description
camera	const mk_camera2d *	Camera to apply.
canvas	mk_canvas_t	Destination Canvas.

Returns True on success.

mk_camera2d_begin_spritefunction

bool mk_camera2d_begin_sprite(const mk_camera2d *camera, struct mk_sprite_ctx *sprite)

Push a camera transform and viewport clip onto a sprite context.

Parameter	Type	Description
camera	const mk_camera2d *	Camera to apply.
sprite	struct mk_sprite_ctx *	Destination sprite context.

Returns True on success.

mk_camera2d_end_canvasfunction

bool mk_camera2d_end_canvas(mk_canvas_t canvas)

Pop a camera transform and viewport clip from a Canvas.

Parameter	Type	Description
canvas	mk_canvas_t	Destination Canvas.

Returns True on success.

mk_camera2d_end_spritefunction

bool mk_camera2d_end_sprite(struct mk_sprite_ctx *sprite)

Pop a camera transform and viewport clip from a sprite context.

Parameter	Type	Description
sprite	struct mk_sprite_ctx *	Destination sprite context.

Returns True on success.

mk_camera2d_is_validfunction

bool mk_camera2d_is_valid(const mk_camera2d *camera)

Test whether a camera and its viewport are usable.

Parameter	Type	Description
camera	const mk_camera2d *	Camera to inspect.

Returns True when valid.

mk_camera2d_makefunction

mk_camera2d mk_camera2d_make(mk_viewport2d viewport, float pixels_per_meter)

Create an origin-centered camera with zero rotation and unit zoom.

Parameter	Type	Description
viewport	mk_viewport2d	Output viewport.
pixels_per_meter	float	Virtual pixels per world unit.

Returns The initialized camera.

mk_camera2d_screen_scalefunction

float mk_camera2d_screen_scale(const mk_camera2d *camera)

Get virtual screen pixels per world unit after zoom.

Parameter	Type	Description
camera	const mk_camera2d *	Camera to inspect.

Returns The scale, or zero for an invalid camera.

mk_camera2d_screen_to_worldfunction

bool mk_camera2d_screen_to_world(const mk_camera2d *camera, float screen_x, float screen_y, float *world_x, float *world_y)

Convert output coordinates to unclamped world coordinates.

Parameter	Type	Description
camera	const mk_camera2d *	Source camera.
screen_x	float	Output-space x coordinate.
screen_y	float	Output-space y coordinate.
world_x	float *	Receives the world x coordinate.
world_y	float *	Receives the world y coordinate.

Returns True when the input point lies inside the viewport content.

mk_camera2d_visible_boundsfunction

bool mk_camera2d_visible_bounds(const mk_camera2d *camera, float *out_min_x, float *out_min_y, float *out_max_x, float *out_max_y)

Compute the conservative world-space AABB of the visible region.

Conservative under rotation: the visible area is a rotated rectangle and this returns its bounding box, so it can report more than is strictly on screen never less.

Parameter	Type	Description
camera	const mk_camera2d *	Source camera.
out_min_x	float *	Optional destination for the minimum x coordinate.
out_min_y	float *	Optional destination for the minimum y coordinate.
out_max_x	float *	Optional destination for the maximum x coordinate.
out_max_y	float *	Optional destination for the maximum y coordinate.

Returns False for an invalid camera; output pointers are not written then.

mk_camera2d_world_to_screenfunction

void mk_camera2d_world_to_screen(const mk_camera2d *camera, float world_x, float world_y, float *screen_x, float *screen_y)

Convert world coordinates to output coordinates.

Parameter	Type	Description
camera	const mk_camera2d *	Source camera.
world_x	float	World x coordinate.
world_y	float	World y coordinate.
screen_x	float *	Receives output x.
screen_y	float *	Receives output y.

mk_viewport2d_begin_canvasfunction

bool mk_viewport2d_begin_canvas(const mk_viewport2d *viewport, mk_canvas_t canvas)

Push a viewport transform and clip onto a Canvas.

Parameter	Type	Description
viewport	const mk_viewport2d *	Viewport to apply.
canvas	mk_canvas_t	Destination Canvas.

Returns True on success.

mk_viewport2d_begin_spritefunction

bool mk_viewport2d_begin_sprite(const mk_viewport2d *viewport, struct mk_sprite_ctx *sprite)

Push a viewport transform and clip onto a sprite context.

Parameter	Type	Description
viewport	const mk_viewport2d *	Viewport to apply.
sprite	struct mk_sprite_ctx *	Destination sprite context.

Returns True on success.

mk_viewport2d_end_canvasfunction

bool mk_viewport2d_end_canvas(mk_canvas_t canvas)

Pop a viewport transform and clip from a Canvas.

Parameter	Type	Description
canvas	mk_canvas_t	Destination Canvas.

Returns True on success.

mk_viewport2d_end_spritefunction

bool mk_viewport2d_end_sprite(struct mk_sprite_ctx *sprite)

Pop a viewport transform and clip from a sprite context.

Parameter	Type	Description
sprite	struct mk_sprite_ctx *	Destination sprite context.

Returns True on success.

mk_viewport2d_is_validfunction

bool mk_viewport2d_is_valid(const mk_viewport2d *viewport)

Test whether a viewport can be used for coordinate conversion.

Parameter	Type	Description
viewport	const mk_viewport2d *	Viewport to inspect.

Returns True when valid.

mk_viewport2d_makefunction

mk_viewport2d mk_viewport2d_make(float virtual_width, float virtual_height, float output_width, float output_height, mk_viewport2d_scale_mode mode)

Build a centered fit or integer-fit viewport.

Parameter	Type	Description
virtual_width	float	Logical content width.
virtual_height	float	Logical content height.
output_width	float	Physical output width.
output_height	float	Physical output height.
mode	mk_viewport2d_scale_mode	Scaling policy.

Returns The computed viewport; valid is false for invalid dimensions.

mk_viewport2d_resizefunction

bool mk_viewport2d_resize(mk_viewport2d *viewport, float output_width, float output_height)

Recompute a viewport for a resized output.

Parameter	Type	Description
viewport	mk_viewport2d *	Viewport to update.
output_width	float	New physical width.
output_height	float	New physical height.

Returns True when the resized viewport is valid.

mk_viewport2d_screen_to_virtualfunction

bool mk_viewport2d_screen_to_virtual(const mk_viewport2d *viewport, float screen_x, float screen_y, float *virtual_x, float *virtual_y)

Convert output coordinates to unclamped virtual coordinates.

Parameter	Type	Description
viewport	const mk_viewport2d *	Source viewport.
screen_x	float	Output-space x coordinate.
screen_y	float	Output-space y coordinate.
virtual_x	float *	Receives the virtual x coordinate.
virtual_y	float *	Receives the virtual y coordinate.

Returns True when the input point lies inside the viewport content.

mk_viewport2d_virtual_to_screenfunction

void mk_viewport2d_virtual_to_screen(const mk_viewport2d *viewport, float virtual_x, float virtual_y, float *screen_x, float *screen_y)

Convert virtual coordinates to output coordinates.

Parameter	Type	Description
viewport	const mk_viewport2d *	Source viewport.
virtual_x	float	Virtual x coordinate.
virtual_y	float	Virtual y coordinate.
screen_x	float *	Receives output x.
screen_y	float *	Receives output y.

Structs

mk_camera2dstruct

Y-down world camera projected through a virtual-resolution viewport.

Field	Type	Description
viewport	mk_viewport2d	Output viewport.
x	float	Camera center in world units.
y	float	Camera center in world units.
rotation	float	Clockwise rotation in radians.
zoom	float	World magnification multiplier.
pixels_per_meter	float	Virtual pixels per world unit at zoom 1.

mk_viewport2dstruct

Centered virtual-resolution viewport mapped into an output surface.

Field	Type	Description
virtual_width	float	Logical content width.
virtual_height	float	Logical content height.
output_width	float	Physical output width.
output_height	float	Physical output height.
scale	float	Output pixels per virtual unit.
offset_x	float	Horizontal output offset of the content.
offset_y	float	Vertical output offset of the content.
mode	mk_viewport2d_scale_mode	Active scaling policy.
valid	bool	Whether all dimensions produce a usable viewport.

Enums

mk_viewport2d_scale_modeenum

Scaling policy for mapping a virtual canvas to an output surface.

Value	Description
MK_VIEWPORT2D_FIT	Preserve aspect ratio using any positive scale.
MK_VIEWPORT2D_INTEGER_FIT	Preserve aspect ratio using an integer scale when possible.

Typedefs

mk_camera2dtypedef

typedef struct mk_camera2d mk_camera2d

Y-down world camera projected through a virtual-resolution viewport.

mk_viewport2dtypedef

typedef struct mk_viewport2d mk_viewport2d

Centered virtual-resolution viewport mapped into an output surface.

mk_viewport2d_scale_modetypedef

typedef enum mk_viewport2d_scale_mode mk_viewport2d_scale_mode

Scaling policy for mapping a virtual canvas to an output surface.