World Extents API

The world extents define an axis-aligned bounding box (AABB) in world space that represents the programmer's declared drawing area. More...

Functions
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 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_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 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_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 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_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

The world extents define an axis-aligned bounding box (AABB) in world space that represents the programmer's declared drawing area.

This is used by wxbgi_cam_fit_to_extents() and can be queried at any time.

The extents start in an "empty" state (no data) and grow as points are added.

Function Documentation

wxbgi_cam_fit_to_extents()

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.

Orthographic cameras (including 2-D cameras): the ortho extents are set so the full AABB is visible with 5 % padding on each side. For 2-D cameras the pan is centred on the AABB and the zoom is adjusted.

Perspective cameras: the eye is moved along the current view direction (keeping the existing target) to a distance where the AABB's bounding sphere fits within the field of view.

Does nothing if no world extents have been set.

Parameters

camName

Camera name, or NULL for the active camera.

Returns

1 on success, 0 if no extents are set, -1 if camera not found.

wxbgi_expand_world_extents()

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).

If no extents have been set the point becomes the initial AABB.

wxbgi_get_world_extents()

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.

Any output pointer may be NULL. If no extents have been set, all values are 0. Check the return value: 1 = extents set, 0 = no data yet.

wxbgi_reset_world_extents()

BGI_API void BGI_CALL wxbgi_reset_world_extents

(

void

)

Resets the world extents to the "empty / no data" state.

wxbgi_set_world_extents()

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.

Replaces any previously set extents. After this call hasData is true.

wxbgi_ucs_circle()

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.

NULL ucsName = active UCS.

wxbgi_ucs_line()

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.

NULL ucsName = active UCS.

wxbgi_ucs_outtextxy()

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.

NULL ucsName = active UCS.

wxbgi_ucs_point()

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.

NULL ucsName = active UCS.

wxbgi_ucs_polyline()

BGI_API void BGI_CALL wxbgi_ucs_polyline	(	const char *	ucsName,
		const float *	xyzTriplets,
		int	pointCount
	)

Draws an open polyline through UCS-local points.

NULL ucsName = active UCS.

Parameters

xyzTriplets

Flat (x,y,z) array in UCS local space.

wxbgi_ucs_to_screen()

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.

Full pipeline: UCS-local -> world -> view -> NDC -> screen pixel.

Parameters

ucsName	UCS name, or NULL for the active UCS.
camName	Camera name, or NULL for the active camera.
ux,uy,uz	UCS-local input point.
screenX	Output screen X pixel (top-left origin, Y increasing down).
screenY	Output screen Y pixel.

Returns

1 if the point is visible, 0 if clipped, -1 if not found.

wxbgi_world_circle()

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.

The screen radius is estimated from a radial offset along world-X.

wxbgi_world_ellipse()

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).

Parameters

startAngle	Arc start in degrees (0=right, CCW).
endAngle	Arc end.

wxbgi_world_fillpoly()

BGI_API void BGI_CALL wxbgi_world_fillpoly	(	const float *	xyzTriplets,
		int	pointCount
	)

Draws and fills a closed polygon through world-space points.

Points behind the camera are dropped; needs >= 3 visible vertices.

wxbgi_world_line()

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.

wxbgi_world_outtextxy()

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.

wxbgi_world_point()

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.

Parameters

x,y,z	World-space position.
color	BGI colour index.

wxbgi_world_polyline()

BGI_API void BGI_CALL wxbgi_world_polyline	(	const float *	xyzTriplets,
		int	pointCount
	)

Draws an open polyline through world-space points.

Parameters

xyzTriplets

Flat (x,y,z) array; length = pointCount*3.

wxbgi_world_rectangle()

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.