Camera Viewport API

Macros
#define	WXBGI_CAM_ORTHO   0
	Create an orthographic camera (parallel projection).
#define	WXBGI_CAM_PERSPECTIVE   1
	Create a perspective camera (converging projection).

Functions
BGI_API int BGI_CALL	wxbgi_cam_create (const char *name, int type)
	Creates a named camera and adds it to the registry.
BGI_API void BGI_CALL	wxbgi_cam_destroy (const char *name)
	Removes a named camera from the registry.
BGI_API const char *BGI_CALL	wxbgi_cam_get_active (void)
	Returns the name of the currently active camera.
BGI_API void BGI_CALL	wxbgi_cam_get_eye (const char *name, float *x, float *y, float *z)
	Retrieves the current eye position.
BGI_API void BGI_CALL	wxbgi_cam_get_proj_matrix (const char *name, float *out16)
	Writes the projection matrix into out16 (column-major float[16]).
BGI_API void BGI_CALL	wxbgi_cam_get_target (const char *name, float *x, float *y, float *z)
	Retrieves the current look-at target.
BGI_API void BGI_CALL	wxbgi_cam_get_up (const char *name, float *x, float *y, float *z)
	Retrieves the current up vector.
BGI_API void BGI_CALL	wxbgi_cam_get_view_matrix (const char *name, float *out16)
	Writes the view matrix into out16 (column-major float[16]).
BGI_API void BGI_CALL	wxbgi_cam_get_vp_matrix (const char *name, float *out16)
	Writes the combined view-projection matrix into out16.
BGI_API void BGI_CALL	wxbgi_cam_screen_to_ray (const char *name, float screenX, float screenY, float *rayOx, float *rayOy, float *rayOz, float *rayDx, float *rayDy, float *rayDz)
	Unprojects a screen pixel to a world-space ray.
BGI_API void BGI_CALL	wxbgi_cam_set_active (const char *name)
	Sets the active camera used by wxbgi_cam_world_to_screen and related helpers when NULL is passed as the camera name.
BGI_API void BGI_CALL	wxbgi_cam_set_eye (const char *name, float x, float y, float z)
	Sets the eye (camera position) in world space.
BGI_API void BGI_CALL	wxbgi_cam_set_ortho (const char *name, float left, float right, float bottom, float top, float nearPlane, float farPlane)
	Sets explicit orthographic clip extents.
BGI_API void BGI_CALL	wxbgi_cam_set_ortho_auto (const char *name, float worldUnitsHigh, float nearPlane, float farPlane)
	Sets orthographic projection with automatic aspect-correct extents.
BGI_API void BGI_CALL	wxbgi_cam_set_perspective (const char *name, float fovYDeg, float nearPlane, float farPlane)
	Switches a camera to perspective projection.
BGI_API void BGI_CALL	wxbgi_cam_set_screen_viewport (const char *name, int x, int y, int w, int h)
	Restricts the camera's output to a sub-rectangle of the window.
BGI_API void BGI_CALL	wxbgi_cam_set_target (const char *name, float x, float y, float z)
	Sets the look-at target in world space.
BGI_API void BGI_CALL	wxbgi_cam_set_up (const char *name, float x, float y, float z)
	Sets the up vector.
BGI_API int BGI_CALL	wxbgi_cam_world_to_screen (const char *name, float wx, float wy, float wz, float *screenX, float *screenY)
	Projects a world-space point to a screen pixel coordinate.

Detailed Description

Macro Definition Documentation

WXBGI_CAM_ORTHO

#define WXBGI_CAM_ORTHO   0

Create an orthographic camera (parallel projection).

WXBGI_CAM_PERSPECTIVE

#define WXBGI_CAM_PERSPECTIVE   1

Create a perspective camera (converging projection).

Function Documentation

wxbgi_cam_create()

BGI_API int BGI_CALL wxbgi_cam_create	(	const char *	name,
		int	type
	)

Creates a named camera and adds it to the registry.

Returns an error if a camera with the same name already exists. The reserved name "default" (created automatically by initwindow()) is always rejected. Newly created cameras have the following defaults:

• Orthographic projection; eye at (0,-10,5) looking at (0,0,0); Z-up.
• Auto-fit ortho extents (2 world-units tall).
• Screen viewport: full window.

Parameters

name	Camera identifier string (UTF-8, must not be NULL).
type	WXBGI_CAM_ORTHO or WXBGI_CAM_PERSPECTIVE.

Returns

1 on success, 0 on invalid input, -1 if no window is open, -2 if a camera with that name already exists (sets graphresult() to grDuplicateName).

wxbgi_cam_destroy()

BGI_API void BGI_CALL wxbgi_cam_destroy

(

const char *

name

)

Removes a named camera from the registry.

The "default" camera cannot be destroyed.

wxbgi_cam_get_active()

BGI_API const char *BGI_CALL wxbgi_cam_get_active

(

void

)

Returns the name of the currently active camera.

The returned pointer is valid until the next call to this function from the same thread.

wxbgi_cam_get_eye()

BGI_API void BGI_CALL wxbgi_cam_get_eye	(	const char *	name,
		float *	x,
		float *	y,
		float *	z
	)

Retrieves the current eye position.

wxbgi_cam_get_proj_matrix()

BGI_API void BGI_CALL wxbgi_cam_get_proj_matrix	(	const char *	name,
		float *	out16
	)

Writes the projection matrix into out16 (column-major float[16]).

Parameters

name	Camera name, or NULL for the active camera.

wxbgi_cam_get_target()

BGI_API void BGI_CALL wxbgi_cam_get_target	(	const char *	name,
		float *	x,
		float *	y,
		float *	z
	)

Retrieves the current look-at target.

wxbgi_cam_get_up()

BGI_API void BGI_CALL wxbgi_cam_get_up	(	const char *	name,
		float *	x,
		float *	y,
		float *	z
	)

Retrieves the current up vector.

wxbgi_cam_get_view_matrix()

BGI_API void BGI_CALL wxbgi_cam_get_view_matrix	(	const char *	name,
		float *	out16
	)

Writes the view matrix into out16 (column-major float[16]).

Parameters

name	Camera name, or NULL for the active camera.

wxbgi_cam_get_vp_matrix()

BGI_API void BGI_CALL wxbgi_cam_get_vp_matrix	(	const char *	name,
		float *	out16
	)

Writes the combined view-projection matrix into out16.

Parameters

name	Camera name, or NULL for the active camera.

wxbgi_cam_screen_to_ray()

BGI_API void BGI_CALL wxbgi_cam_screen_to_ray	(	const char *	name,
		float	screenX,
		float	screenY,
		float *	rayOx,
		float *	rayOy,
		float *	rayOz,
		float *	rayDx,
		float *	rayDy,
		float *	rayDz
	)

Unprojects a screen pixel to a world-space ray.

The ray originates on the near clip plane. The direction vector is normalised. Screen coordinates follow the BGI top-left / Y-down convention.

Parameters

name	Camera name, or NULL for the active camera.
screenX,screenY	Input screen pixel.
rayOx,rayOy,rayOz	Output ray origin (world space, may be NULL).
rayDx,rayDy,rayDz	Output normalised ray direction (may be NULL).

wxbgi_cam_set_active()

BGI_API void BGI_CALL wxbgi_cam_set_active

(

const char *

name

)

Sets the active camera used by wxbgi_cam_world_to_screen and related helpers when NULL is passed as the camera name.

wxbgi_cam_set_eye()

BGI_API void BGI_CALL wxbgi_cam_set_eye	(	const char *	name,
		float	x,
		float	y,
		float	z
	)

Sets the eye (camera position) in world space.

Parameters

name	Camera name, or NULL for the active camera.

wxbgi_cam_set_ortho()

BGI_API void BGI_CALL wxbgi_cam_set_ortho	(	const char *	name,
		float	left,
		float	right,
		float	bottom,
		float	top,
		float	nearPlane,
		float	farPlane
	)

Sets explicit orthographic clip extents.

Parameters

name	Camera name, or NULL for the active camera.
left	Left world-unit boundary.
right	Right world-unit boundary.
bottom	Bottom world-unit boundary (use > top for Y-flip).
top	Top world-unit boundary.
nearPlane	Near clip distance (may be negative for 2-D use).
farPlane	Far clip distance.

wxbgi_cam_set_ortho_auto()

BGI_API void BGI_CALL wxbgi_cam_set_ortho_auto	(	const char *	name,
		float	worldUnitsHigh,
		float	nearPlane,
		float	farPlane
	)

Sets orthographic projection with automatic aspect-correct extents.

The visible width is computed automatically from the camera's screen viewport aspect ratio so that worldUnitsHigh world-units are always visible vertically.

Parameters

name	Camera name, or NULL for the active camera.
worldUnitsHigh	Visible height in world units.
nearPlane	Near clip distance.
farPlane	Far clip distance.

wxbgi_cam_set_perspective()

BGI_API void BGI_CALL wxbgi_cam_set_perspective	(	const char *	name,
		float	fovYDeg,
		float	nearPlane,
		float	farPlane
	)

Switches a camera to perspective projection.

Parameters

name	Camera name, or NULL for the active camera.
fovYDeg	Vertical field-of-view in degrees.
nearPlane	Near clip distance (positive, e.g. 0.1).
farPlane	Far clip distance (e.g. 10000).

wxbgi_cam_set_screen_viewport()

BGI_API void BGI_CALL wxbgi_cam_set_screen_viewport	(	const char *	name,
		int	x,
		int	y,
		int	w,
		int	h
	)

Restricts the camera's output to a sub-rectangle of the window.

Pass all zeros to use the full window (default).

Parameters

name	Camera name, or NULL for the active camera.
x,y	Top-left corner of the viewport in pixels.
w,h	Viewport width and height in pixels.

wxbgi_cam_set_target()

BGI_API void BGI_CALL wxbgi_cam_set_target	(	const char *	name,
		float	x,
		float	y,
		float	z
	)

Sets the look-at target in world space.

Parameters

name	Camera name, or NULL for the active camera.

wxbgi_cam_set_up()

BGI_API void BGI_CALL wxbgi_cam_set_up	(	const char *	name,
		float	x,
		float	y,
		float	z
	)

Sets the up vector.

For Z-up worlds use (0, 0, 1).

Parameters

name	Camera name, or NULL for the active camera.

wxbgi_cam_world_to_screen()

BGI_API int BGI_CALL wxbgi_cam_world_to_screen	(	const char *	name,
		float	wx,
		float	wy,
		float	wz,
		float *	screenX,
		float *	screenY
	)

Projects a world-space point to a screen pixel coordinate.

Screen coordinates follow the classic BGI convention: (0,0) is the top-left corner of the window and Y increases downward.

Parameters

name	Camera name, or NULL for the active camera.
wx,wy,wz	World-space point.
screenX	Output screen X pixel (may be NULL).
screenY	Output screen Y pixel (may be NULL).

Returns

1 if the point is visible (inside the view frustum), 0 if clipped, -1 if the camera is not found or no window is open.