User Coordinate System (UCS) API

A UCS defines a named local coordinate frame inside the Z-up, right-handed world space. More...

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

Detailed Description

A UCS defines a named local coordinate frame inside the Z-up, right-handed world space.

It consists of an origin point and three orthonormal axes (X, Y, Z) expressed as world-space direction vectors.

A UCS named "world" (the identity frame) is created automatically on initwindow() / initgraph() and cannot be destroyed.

All functions accept NULL as name to target the currently active UCS.

Function Documentation

wxbgi_ucs_align_to_plane()

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.

Equivalent to calling wxbgi_ucs_set_origin followed by an axis assignment where Z = normal. The X and Y axes are chosen automatically to form a complete right-handed frame.

Parameters

name	UCS name, or NULL for the active UCS.
nx,ny,nz	Surface normal (need not be unit length).
ox,oy,oz	New UCS origin in world space.

wxbgi_ucs_create()

BGI_API int BGI_CALL wxbgi_ucs_create

(

const char *

name

)

Creates a named UCS initialised to the world identity frame.

Returns an error if a UCS with the same name already exists. The reserved name "world" (created automatically by initwindow()) is always rejected.

Parameters

name	UCS identifier string (must not be NULL or empty).

Returns

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

wxbgi_ucs_destroy()

BGI_API void BGI_CALL wxbgi_ucs_destroy

(

const char *

name

)

Removes a named UCS from the registry.

The "world" UCS cannot be destroyed.

wxbgi_ucs_get_active()

BGI_API const char *BGI_CALL wxbgi_ucs_get_active

(

void

)

Returns the name of the currently active UCS.

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

wxbgi_ucs_get_axes()

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.

Any of the output pointers may be NULL to skip that axis.

wxbgi_ucs_get_local_to_world_matrix()

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

Parameters

name	UCS name, or NULL for the active UCS.

wxbgi_ucs_get_origin()

BGI_API void BGI_CALL wxbgi_ucs_get_origin	(	const char *	name,
		float *	ox,
		float *	oy,
		float *	oz
	)

Retrieves the current UCS origin.

wxbgi_ucs_get_world_to_local_matrix()

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

Parameters

name	UCS name, or NULL for the active UCS.

wxbgi_ucs_local_to_world()

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.

Parameters

name	UCS name, or NULL for the active UCS.
lx,ly,lz	UCS local input point.
wx,wy,wz	Output world-space coordinates (any may be NULL).

wxbgi_ucs_set_active()

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.

wxbgi_ucs_set_axes()

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.

The vectors are orthonormalised automatically (Gram-Schmidt), so it is sufficient to supply two perpendicular vectors and let the library compute the third. The Z axis is recomputed as xAxis × yAxis.

Parameters

name	UCS name, or NULL for the active UCS.
xx,xy,xz	World-space direction of the local X axis.
yx,yy,yz	World-space direction of the local Y axis.
zx,zy,zz	World-space direction of the local Z axis (overridden by the cross product after normalisation).

wxbgi_ucs_set_origin()

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.

Parameters

name	UCS name, or NULL for the active UCS.

wxbgi_ucs_world_to_local()

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.

Parameters

name	UCS name, or NULL for the active UCS.
wx,wy,wz	World-space input point.
lx,ly,lz	Output UCS local coordinates (any may be NULL).