wx_bgi_3d.h File Reference

Camera viewport and 3-D world coordinate extension API. More...

#include "bgi_types.h"

Include dependency graph for wx_bgi_3d.h:

Go to the source code of this file.

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_cam2d_create (const char *name)
	Creates a 2-D overhead camera.
BGI_API void BGI_CALL	wxbgi_cam2d_get_pan (const char *name, float *x, float *y)
	Retrieves the current pan position.
BGI_API void BGI_CALL	wxbgi_cam2d_get_rotation (const char *name, float *angleDeg)
	Retrieves the current rotation in degrees.
BGI_API void BGI_CALL	wxbgi_cam2d_get_zoom (const char *name, float *zoom)
	Retrieves the current zoom level.
BGI_API void BGI_CALL	wxbgi_cam2d_pan_by (const char *name, float dx, float dy)
	Pans the 2-D camera by a world-space delta.
BGI_API void BGI_CALL	wxbgi_cam2d_set_pan (const char *name, float x, float y)
	Sets the 2-D camera pan (world-space centre of the view).
BGI_API void BGI_CALL	wxbgi_cam2d_set_rotation (const char *name, float angleDeg)
	Sets the 2-D view rotation around the Z axis.
BGI_API void BGI_CALL	wxbgi_cam2d_set_world_height (const char *name, float worldUnitsHigh)
	Sets the number of world-units visible vertically at zoom = 1.
BGI_API void BGI_CALL	wxbgi_cam2d_set_zoom (const char *name, float zoom)
	Sets the zoom level (1 = nominal, 2 = 2× magnification).
BGI_API void BGI_CALL	wxbgi_cam2d_zoom_at (const char *name, float factor, float pivotX, float pivotY)
	Zooms around a pivot point in world space.
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 int BGI_CALL	wxbgi_cam_fit_to_extents (const char *camName)
	Adjusts a camera's projection and position to frame the world extents.
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.
BGI_API void BGI_CALL	wxbgi_expand_world_extents (float x, float y, float z)
	Expands the world extents to include the point (x, y, z).
BGI_API int BGI_CALL	wxbgi_get_world_extents (float *minX, float *minY, float *minZ, float *maxX, float *maxY, float *maxZ)
	Retrieves the current world extents.
BGI_API void BGI_CALL	wxbgi_reset_world_extents (void)
	Resets the world extents to the "empty / no data" state.
BGI_API void BGI_CALL	wxbgi_set_world_extents (float minX, float minY, float minZ, float maxX, float maxY, float maxZ)
	Sets the world extents to an explicit AABB.
BGI_API void BGI_CALL	wxbgi_ucs_align_to_plane (const char *name, float nx, float ny, float nz, float ox, float oy, float oz)
	Aligns a UCS so that its local Z axis matches a given surface normal.
BGI_API void BGI_CALL	wxbgi_ucs_circle (const char *ucsName, float cx, float cy, float cz, float radius)
	Draws a circle at a UCS-local centre with a UCS-unit radius.
BGI_API int BGI_CALL	wxbgi_ucs_create (const char *name)
	Creates a named UCS initialised to the world identity frame.
BGI_API void BGI_CALL	wxbgi_ucs_destroy (const char *name)
	Removes a named UCS from the registry.
BGI_API const char *BGI_CALL	wxbgi_ucs_get_active (void)
	Returns the name of the currently active UCS.
BGI_API void BGI_CALL	wxbgi_ucs_get_axes (const char *name, float *xx, float *xy, float *xz, float *yx, float *yy, float *yz, float *zx, float *zy, float *zz)
	Retrieves all three axes of a UCS as world-space unit vectors.
BGI_API void BGI_CALL	wxbgi_ucs_get_local_to_world_matrix (const char *name, float *out16)
	Writes the local-to-world matrix into out16 (column-major float[16]).
BGI_API void BGI_CALL	wxbgi_ucs_get_origin (const char *name, float *ox, float *oy, float *oz)
	Retrieves the current UCS origin.
BGI_API void BGI_CALL	wxbgi_ucs_get_world_to_local_matrix (const char *name, float *out16)
	Writes the world-to-local matrix into out16 (column-major float[16]).
BGI_API void BGI_CALL	wxbgi_ucs_line (const char *ucsName, float ux1, float uy1, float uz1, float ux2, float uy2, float uz2)
	Draws a line between two UCS-local points.
BGI_API void BGI_CALL	wxbgi_ucs_local_to_world (const char *name, float lx, float ly, float lz, float *wx, float *wy, float *wz)
	Transforms a UCS local point into world-space coordinates.
BGI_API void BGI_CALL	wxbgi_ucs_outtextxy (const char *ucsName, float ux, float uy, float uz, const char *text)
	Draws text at a UCS-local anchor.
BGI_API void BGI_CALL	wxbgi_ucs_point (const char *ucsName, float ux, float uy, float uz, int color)
	Draws a pixel at a UCS-local position.
BGI_API void BGI_CALL	wxbgi_ucs_polyline (const char *ucsName, const float *xyzTriplets, int pointCount)
	Draws an open polyline through UCS-local points.
BGI_API void BGI_CALL	wxbgi_ucs_set_active (const char *name)
	Sets the active UCS used when NULL is passed as the UCS name.
BGI_API void BGI_CALL	wxbgi_ucs_set_axes (const char *name, float xx, float xy, float xz, float yx, float yy, float yz, float zx, float zy, float zz)
	Sets all three axes of a UCS.
BGI_API void BGI_CALL	wxbgi_ucs_set_origin (const char *name, float ox, float oy, float oz)
	Sets the origin of a UCS in world space.
BGI_API int BGI_CALL	wxbgi_ucs_to_screen (const char *ucsName, const char *camName, float ux, float uy, float uz, float *screenX, float *screenY)
	Projects a UCS-local point through the named UCS and camera to screen-pixel coordinates.
BGI_API void BGI_CALL	wxbgi_ucs_world_to_local (const char *name, float wx, float wy, float wz, float *lx, float *ly, float *lz)
	Transforms a world-space point into UCS local coordinates.
BGI_API void BGI_CALL	wxbgi_world_circle (float cx, float cy, float cz, float radius)
	Draws a circle (world-space centre, world-unit radius) via the active camera.
BGI_API void BGI_CALL	wxbgi_world_ellipse (float cx, float cy, float cz, float rx, float ry, int startAngle, int endAngle)
	Draws an ellipse arc (world-space centre, world-unit semi-axes rx/ry).
BGI_API void BGI_CALL	wxbgi_world_fillpoly (const float *xyzTriplets, int pointCount)
	Draws and fills a closed polygon through world-space points.
BGI_API void BGI_CALL	wxbgi_world_line (float x1, float y1, float z1, float x2, float y2, float z2)
	Draws a line segment between two world-space points using the current colour/style.
BGI_API void BGI_CALL	wxbgi_world_outtextxy (float x, float y, float z, const char *text)
	Draws text at a world-space position using current BGI font/colour settings.
BGI_API void BGI_CALL	wxbgi_world_point (float x, float y, float z, int color)
	Draws a single pixel at a world-space position.
BGI_API void BGI_CALL	wxbgi_world_polyline (const float *xyzTriplets, int pointCount)
	Draws an open polyline through world-space points.
BGI_API void BGI_CALL	wxbgi_world_rectangle (float x1, float y1, float z1, float x2, float y2, float z2)
	Draws a screen-space rectangle outline from two projected world-space corners.

Detailed Description

Camera viewport and 3-D world coordinate extension API.

All functions are prefixed with wxbgi_cam_ (3-D camera) or wxbgi_cam2d_ (2-D overhead camera convenience wrapper) to avoid collisions with the classic BGI symbols in wx_bgi.h.

Coordinate system: Z-up, right-handed (AutoCAD / engineering style). The XY plane is the ground plane; +Z points upward. For 2-D cameras the ground plane is the canvas and the camera looks straight down from +Z.

Default camera: A camera named "default" is created automatically by initwindow() / initgraph(). It is a pixel-space orthographic camera where world coordinate (0,0) maps to the top-left screen pixel and world coordinate (windowWidth, windowHeight) maps to the bottom-right pixel, exactly replicating the classic BGI coordinate system. Classic BGI drawing functions are unaffected by the camera system.

Thread safety: All functions acquire the internal library mutex.