wx_BGI_Graphics
Classic BGI-compatible graphics API with modern OpenGL extension API
Loading...
Searching...
No Matches
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
nameUCS name, or NULL for the active UCS.
nx,ny,nzSurface normal (need not be unit length).
ox,oy,ozNew 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
nameUCS 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
nameUCS name, or NULL for the active UCS.
out16Output buffer receiving 16 floats in column-major order.

◆ 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
nameUCS name, or NULL for the active UCS.
out16Output buffer receiving 16 floats in column-major order.

◆ 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
nameUCS name, or NULL for the active UCS.
lx,ly,lzUCS local input point.
wx,wy,wzOutput 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
nameUCS name, or NULL for the active UCS.
xx,xy,xzWorld-space direction of the local X axis.
yx,yy,yzWorld-space direction of the local Y axis.
zx,zy,zzWorld-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
nameUCS name, or NULL for the active UCS.
oxWorld-space X coordinate of the UCS origin.
oyWorld-space Y coordinate of the UCS origin.
ozWorld-space Z coordinate of the UCS origin.

◆ 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
nameUCS name, or NULL for the active UCS.
wx,wy,wzWorld-space input point.
lx,ly,lzOutput UCS local coordinates (any may be NULL).