wx_bgi_dds.h File Reference

Public C API for the Drawing Description Data Structure (DDS). More...

#include "bgi_types.h"

Include dependency graph for wx_bgi_dds.h:

Go to the source code of this file.

Macros
#define	WXBGI_COORD_BGI_PIXEL   0
	Classic BGI pixel coords stored as world (x, y, 0).
#define	WXBGI_COORD_UCS_LOCAL   2
	UCS-local float coords.
#define	WXBGI_COORD_WORLD_3D   1
	World-space 3-D float coords.
#define	WXBGI_DDS_ARC   6
#define	WXBGI_DDS_BAR   12
#define	WXBGI_DDS_BAR3D   13
#define	WXBGI_DDS_BOX   18
#define	WXBGI_DDS_CAMERA   0
#define	WXBGI_DDS_CIRCLE   5
#define	WXBGI_DDS_CONE   21
#define	WXBGI_DDS_CYLINDER   20
#define	WXBGI_DDS_ELLIPSE   7
#define	WXBGI_DDS_EXTRUSION   25
#define	WXBGI_DDS_FILL_ELLIPSE   8
#define	WXBGI_DDS_FILL_POLY   15
#define	WXBGI_DDS_HEIGHTMAP   23
#define	WXBGI_DDS_IMAGE   17
#define	WXBGI_DDS_LINE   4
#define	WXBGI_DDS_PARAM_SURFACE   24
#define	WXBGI_DDS_PIE_SLICE   9
#define	WXBGI_DDS_POINT   3
#define	WXBGI_DDS_POLYGON   14
#define	WXBGI_DDS_RECTANGLE   11
#define	WXBGI_DDS_SECTOR   10
#define	WXBGI_DDS_SPHERE   19
#define	WXBGI_DDS_TEXT   16
#define	WXBGI_DDS_TORUS   22
#define	WXBGI_DDS_UCS   1
#define	WXBGI_DDS_UNKNOWN   -1
#define	WXBGI_DDS_WORLD_EXTENTS   2
#define	WXBGI_PARAM_CYLINDER   1
#define	WXBGI_PARAM_MOBIUS   4
#define	WXBGI_PARAM_SADDLE   3
#define	WXBGI_PARAM_SPHERE   0
#define	WXBGI_PARAM_TORUS   2
#define	WXBGI_SOLID_FLAT   1
	GL Phong flat shading + depth buffer.
#define	WXBGI_SOLID_SMOOTH   2
	GL Phong smooth (Gouraud) shading + depth buffer.
#define	WXBGI_SOLID_SOLID   1
	Backward-compat alias for FLAT.
#define	WXBGI_SOLID_WIREFRAME   0

Functions
BGI_API const char *BGI_CALL	wxbgi_cam_get_scene (const char *camName)
	Returns the name of the scene currently assigned to a camera.
BGI_API void BGI_CALL	wxbgi_cam_set_scene (const char *camName, const char *sceneName)
	Assigns a DDS scene to a camera.
BGI_API void BGI_CALL	wxbgi_dds_clear (void)
	Removes all drawing-primitive objects from the DDS.
BGI_API void BGI_CALL	wxbgi_dds_clear_all (void)
	Removes ALL objects from the DDS including cameras and UCS.
BGI_API const char *BGI_CALL	wxbgi_dds_find_by_label (const char *label)
	Returns the ID of the first non-deleted object with the given label, or "" if not found.
BGI_API int BGI_CALL	wxbgi_dds_from_json (const char *jsonString)
	Replaces the current DDS scene with the data in jsonString.
BGI_API int BGI_CALL	wxbgi_dds_from_yaml (const char *yamlString)
	Replaces the current DDS scene with the data in yamlString.
BGI_API int BGI_CALL	wxbgi_dds_get_coord_space (const char *id)
	Returns the CoordSpace (WXBGI_COORD_*) of a drawing object.
BGI_API const char *BGI_CALL	wxbgi_dds_get_id_at (int index)
	Returns the auto-assigned ID string of the object at position index (0-based insertion order, excluding deleted entries).
BGI_API const char *BGI_CALL	wxbgi_dds_get_label (const char *id)
	Returns the user label of the object identified by id.
BGI_API int BGI_CALL	wxbgi_dds_get_type (const char *id)
	Returns the WXBGI_DDS_* type constant for the object identified by id, or WXBGI_DDS_UNKNOWN if not found.
BGI_API int BGI_CALL	wxbgi_dds_get_visible (const char *id)
	Returns 1 if the object exists and is visible, 0 otherwise.
BGI_API int BGI_CALL	wxbgi_dds_load_json (const char *filePath)
	Loads and restores a DDS from a JSON file at filePath.
BGI_API int BGI_CALL	wxbgi_dds_load_yaml (const char *filePath)
	Loads and restores a DDS from a YAML file at filePath.
BGI_API int BGI_CALL	wxbgi_dds_object_count (void)
	Returns the total number of non-deleted, visible + hidden objects in the DDS (cameras, UCS, drawing primitives).
BGI_API int BGI_CALL	wxbgi_dds_remove (const char *id)
	Soft-deletes the object identified by id.
BGI_API int BGI_CALL	wxbgi_dds_save_json (const char *filePath)
	Serialises the DDS to a JSON file at filePath.
BGI_API int BGI_CALL	wxbgi_dds_save_yaml (const char *filePath)
	Serialises the DDS to a YAML file at filePath.
BGI_API void BGI_CALL	wxbgi_dds_scene_clear (const char *name)
	Clears all drawing-primitive objects from a named scene.
BGI_API int BGI_CALL	wxbgi_dds_scene_create (const char *name)
	Creates a new named DDS scene graph.
BGI_API void BGI_CALL	wxbgi_dds_scene_destroy (const char *name)
	Destroys a named DDS scene graph and all its objects.
BGI_API int BGI_CALL	wxbgi_dds_scene_exists (const char *name)
	Tests whether a named scene exists in the registry.
BGI_API const char *BGI_CALL	wxbgi_dds_scene_get_active (void)
	Returns the name of the currently active scene.
BGI_API void BGI_CALL	wxbgi_dds_scene_set_active (const char *name)
	Sets the active scene for immediate-mode draw calls.
BGI_API void BGI_CALL	wxbgi_dds_set_label (const char *id, const char *label)
	Sets the user label of the object identified by id.
BGI_API void BGI_CALL	wxbgi_dds_set_visible (const char *id, int visible)
	Sets the visibility flag of the object identified by id.
BGI_API const char *BGI_CALL	wxbgi_dds_to_json (void)
	Serialises the full DDS scene to a JSON string (DDJ format).
BGI_API const char *BGI_CALL	wxbgi_dds_to_yaml (void)
	Serialises the full DDS scene to a YAML string (DDY format).
BGI_API void BGI_CALL	wxbgi_gl_pass_destroy (void)
	Release all OpenGL objects managed by the GL render pass.
BGI_API void BGI_CALL	wxbgi_render_dds (const char *camName)
	Renders all visible DDS drawing objects through the named camera into the BGI pixel buffer.
BGI_API void BGI_CALL	wxbgi_set_legacy_gl_render (int enable)
	Enable or disable the legacy per-pixel GL_POINTS rendering path.
BGI_API void BGI_CALL	wxbgi_solid_set_ambient (float a)
	Set the ambient light intensity (0–1).
BGI_API void BGI_CALL	wxbgi_solid_set_diffuse (float d)
	Set the diffuse light intensity (0–1).
BGI_API void BGI_CALL	wxbgi_solid_set_fill_light (float x, float y, float z, float strength)
	Set the secondary (fill) light direction and relative strength.
BGI_API void BGI_CALL	wxbgi_solid_set_light_dir (float x, float y, float z)
	Set the primary (key) light direction.
BGI_API void BGI_CALL	wxbgi_solid_set_light_space (int worldSpace)
	Select light coordinate space.
BGI_API void BGI_CALL	wxbgi_solid_set_specular (float s, float shininess)
	Set the specular intensity and shininess exponent.

Detailed Description

Public C API for the Drawing Description Data Structure (DDS).

The DDS is a retained-mode in-memory scene graph. Every draw call in the library both renders immediately to the pixel buffer AND appends a CHDOP (Class Hierarchy of Drawing Object Primitives) object to the DDS.

Cameras and UCS definitions are also first-class DDS objects; they are serialized and restored as part of the scene.

Usage pattern:

// Draw normally — DDS is populated automatically
circle(400, 300, 80);
wxbgi_world_line(0,0,0, 10,0,0);
 
// Inspect the scene
int n = wxbgi_dds_object_count();
 
// Serialise
const char *json = wxbgi_dds_to_json();
 
// Re-render from DDS through a different camera
cleardevice();
wxbgi_render_dds("cam_perspective");

Include this header in addition to wx_bgi.h and/or wx_bgi_3d.h.

Macro Definition Documentation

WXBGI_COORD_BGI_PIXEL

#define WXBGI_COORD_BGI_PIXEL   0

Classic BGI pixel coords stored as world (x, y, 0).

WXBGI_COORD_UCS_LOCAL

#define WXBGI_COORD_UCS_LOCAL   2

UCS-local float coords.

WXBGI_COORD_WORLD_3D

#define WXBGI_COORD_WORLD_3D   1

World-space 3-D float coords.

WXBGI_DDS_ARC

#define WXBGI_DDS_ARC   6

WXBGI_DDS_BAR

#define WXBGI_DDS_BAR   12

WXBGI_DDS_BAR3D

#define WXBGI_DDS_BAR3D   13

WXBGI_DDS_BOX

#define WXBGI_DDS_BOX   18

WXBGI_DDS_CAMERA

#define WXBGI_DDS_CAMERA   0

WXBGI_DDS_CIRCLE

#define WXBGI_DDS_CIRCLE   5

WXBGI_DDS_CONE

#define WXBGI_DDS_CONE   21

WXBGI_DDS_CYLINDER

#define WXBGI_DDS_CYLINDER   20

WXBGI_DDS_ELLIPSE

#define WXBGI_DDS_ELLIPSE   7

WXBGI_DDS_EXTRUSION

#define WXBGI_DDS_EXTRUSION   25

WXBGI_DDS_FILL_ELLIPSE

#define WXBGI_DDS_FILL_ELLIPSE   8

WXBGI_DDS_FILL_POLY

#define WXBGI_DDS_FILL_POLY   15

WXBGI_DDS_HEIGHTMAP

#define WXBGI_DDS_HEIGHTMAP   23

WXBGI_DDS_IMAGE

#define WXBGI_DDS_IMAGE   17

WXBGI_DDS_LINE

#define WXBGI_DDS_LINE   4

WXBGI_DDS_PARAM_SURFACE

#define WXBGI_DDS_PARAM_SURFACE   24

WXBGI_DDS_PIE_SLICE

#define WXBGI_DDS_PIE_SLICE   9

WXBGI_DDS_POINT

#define WXBGI_DDS_POINT   3

WXBGI_DDS_POLYGON

#define WXBGI_DDS_POLYGON   14

WXBGI_DDS_RECTANGLE

#define WXBGI_DDS_RECTANGLE   11

WXBGI_DDS_SECTOR

#define WXBGI_DDS_SECTOR   10

WXBGI_DDS_SPHERE

#define WXBGI_DDS_SPHERE   19

WXBGI_DDS_TEXT

#define WXBGI_DDS_TEXT   16

WXBGI_DDS_TORUS

#define WXBGI_DDS_TORUS   22

WXBGI_DDS_UCS

#define WXBGI_DDS_UCS   1

WXBGI_DDS_UNKNOWN

#define WXBGI_DDS_UNKNOWN   -1

WXBGI_DDS_WORLD_EXTENTS

#define WXBGI_DDS_WORLD_EXTENTS   2

WXBGI_PARAM_CYLINDER

#define WXBGI_PARAM_CYLINDER   1

WXBGI_PARAM_MOBIUS

#define WXBGI_PARAM_MOBIUS   4

WXBGI_PARAM_SADDLE

#define WXBGI_PARAM_SADDLE   3

WXBGI_PARAM_SPHERE

#define WXBGI_PARAM_SPHERE   0

WXBGI_PARAM_TORUS

#define WXBGI_PARAM_TORUS   2

WXBGI_SOLID_FLAT

#define WXBGI_SOLID_FLAT   1

GL Phong flat shading + depth buffer.

WXBGI_SOLID_SMOOTH

#define WXBGI_SOLID_SMOOTH   2

GL Phong smooth (Gouraud) shading + depth buffer.

WXBGI_SOLID_SOLID

#define WXBGI_SOLID_SOLID   1

Backward-compat alias for FLAT.

WXBGI_SOLID_WIREFRAME

#define WXBGI_SOLID_WIREFRAME   0

Function Documentation

wxbgi_cam_get_scene()

BGI_API const char *BGI_CALL wxbgi_cam_get_scene

(

const char *

camName

)

Returns the name of the scene currently assigned to a camera.

Parameters

camName

Camera name, or NULL/"" for the active camera.

Returns

Scene name string, or NULL if the camera is not found.

wxbgi_cam_set_scene()

BGI_API void BGI_CALL wxbgi_cam_set_scene	(	const char *	camName,
		const char *	sceneName
	)

Assigns a DDS scene to a camera.

After this call, wxbgi_render_dds(camName) will render the specified scene through that camera. If sceneName does not exist the call is a no-op.

Parameters

camName	Camera name, or NULL/"" for the active camera.
sceneName	Name of the scene to assign. NULL/"" selects "default".

wxbgi_dds_clear()

BGI_API void BGI_CALL wxbgi_dds_clear

(

void

)

Removes all drawing-primitive objects from the DDS.

Camera and UCS objects are retained. The screen is NOT cleared; call cleardevice() separately if required.

wxbgi_dds_clear_all()

BGI_API void BGI_CALL wxbgi_dds_clear_all

(

void

)

Removes ALL objects from the DDS including cameras and UCS.

Recreates the default pixel-space camera and the world identity UCS so the library remains in a usable state. The screen is NOT cleared.

wxbgi_dds_find_by_label()

BGI_API const char *BGI_CALL wxbgi_dds_find_by_label

(

const char *

label

)

Returns the ID of the first non-deleted object with the given label, or "" if not found.

Returns a pointer to an internal thread-local buffer.

wxbgi_dds_from_json()

BGI_API int BGI_CALL wxbgi_dds_from_json

(

const char *

jsonString

)

Replaces the current DDS scene with the data in jsonString.

Cameras and UCS objects in the JSON are restored into BgiState::cameras and BgiState::ucsSystems. All existing scene data is discarded first.

Returns

0 on success, -1 on parse error (scene is left empty on error).

wxbgi_dds_from_yaml()

BGI_API int BGI_CALL wxbgi_dds_from_yaml

(

const char *

yamlString

)

Replaces the current DDS scene with the data in yamlString.

Returns

0 on success, -1 on parse error.

wxbgi_dds_get_coord_space()

BGI_API int BGI_CALL wxbgi_dds_get_coord_space

(

const char *

id

)

Returns the CoordSpace (WXBGI_COORD_*) of a drawing object.

Returns -1 for config objects (Camera, Ucs, WorldExtents) or if not found.

wxbgi_dds_get_id_at()

BGI_API const char *BGI_CALL wxbgi_dds_get_id_at

(

int

index

)

Returns the auto-assigned ID string of the object at position index (0-based insertion order, excluding deleted entries).

Returns a pointer to an internal thread-local buffer valid until the next call from the same thread. Returns "" if index is out of range.

wxbgi_dds_get_label()

BGI_API const char *BGI_CALL wxbgi_dds_get_label

(

const char *

id

)

Returns the user label of the object identified by id.

Returns a pointer to an internal thread-local buffer valid until the next call from the same thread. Returns "" if the object has no label or is not found.

wxbgi_dds_get_type()

BGI_API int BGI_CALL wxbgi_dds_get_type

(

const char *

id

)

Returns the WXBGI_DDS_* type constant for the object identified by id, or WXBGI_DDS_UNKNOWN if not found.

wxbgi_dds_get_visible()

BGI_API int BGI_CALL wxbgi_dds_get_visible

(

const char *

id

)

Returns 1 if the object exists and is visible, 0 otherwise.

wxbgi_dds_load_json()

BGI_API int BGI_CALL wxbgi_dds_load_json

(

const char *

filePath

)

Loads and restores a DDS from a JSON file at filePath.

Returns

0 on success, -1 on I/O or parse error.

wxbgi_dds_load_yaml()

BGI_API int BGI_CALL wxbgi_dds_load_yaml

(

const char *

filePath

)

Loads and restores a DDS from a YAML file at filePath.

Returns

0 on success, -1 on I/O or parse error.

wxbgi_dds_object_count()

BGI_API int BGI_CALL wxbgi_dds_object_count

(

void

)

Returns the total number of non-deleted, visible + hidden objects in the DDS (cameras, UCS, drawing primitives).

wxbgi_dds_remove()

BGI_API int BGI_CALL wxbgi_dds_remove

(

const char *

id

)

Soft-deletes the object identified by id.

The object is marked deleted and excluded from future traversals; its memory is freed lazily on the next compact operation (automatic at clearDrawing / clearAll).

Returns

1 on success, 0 if not found.

wxbgi_dds_save_json()

BGI_API int BGI_CALL wxbgi_dds_save_json

(

const char *

filePath

)

Serialises the DDS to a JSON file at filePath.

Returns

0 on success, -1 on I/O error.

wxbgi_dds_save_yaml()

BGI_API int BGI_CALL wxbgi_dds_save_yaml

(

const char *

filePath

)

Serialises the DDS to a YAML file at filePath.

Returns

0 on success, -1 on I/O error.

wxbgi_dds_scene_clear()

BGI_API void BGI_CALL wxbgi_dds_scene_clear

(

const char *

name

)

Clears all drawing-primitive objects from a named scene.

Camera and UCS objects in the scene are retained.

Parameters

name	Scene name, or NULL/"" for the active scene.

wxbgi_dds_scene_create()

BGI_API int BGI_CALL wxbgi_dds_scene_create

(

const char *

name

)

Creates a new named DDS scene graph.

Parameters

name	Non-empty name for the new scene. Must not already exist.

Returns

0 on success, -1 if the name is empty, already exists, or is "default".

wxbgi_dds_scene_destroy()

BGI_API void BGI_CALL wxbgi_dds_scene_destroy

(

const char *

name

)

Destroys a named DDS scene graph and all its objects.

Any cameras assigned to the destroyed scene fall back to rendering the "default" scene. Attempting to destroy "default" is a no-op.

Parameters

name	Name of the scene to destroy.

wxbgi_dds_scene_exists()

BGI_API int BGI_CALL wxbgi_dds_scene_exists

(

const char *

name

)

Tests whether a named scene exists in the registry.

Parameters

name	Scene name to test.

Returns

1 if the scene exists, 0 otherwise.

wxbgi_dds_scene_get_active()

BGI_API const char *BGI_CALL wxbgi_dds_scene_get_active

(

void

)

Returns the name of the currently active scene.

Returns

Pointer to a static string; valid until the next call to this function.

wxbgi_dds_scene_set_active()

BGI_API void BGI_CALL wxbgi_dds_scene_set_active

(

const char *

name

)

Sets the active scene for immediate-mode draw calls.

All subsequent draw calls (circle, box, wxbgi_world_line, etc.) append objects to this scene until changed again. Passing NULL or an empty string selects "default".

Parameters

name	Name of an existing scene, or NULL/"" for "default".

wxbgi_dds_set_label()

BGI_API void BGI_CALL wxbgi_dds_set_label	(	const char *	id,
		const char *	label
	)

Sets the user label of the object identified by id.

Labels are optional and non-unique; they are a convenience for application-level bookkeeping.

wxbgi_dds_set_visible()

BGI_API void BGI_CALL wxbgi_dds_set_visible	(	const char *	id,
		int	visible
	)

Sets the visibility flag of the object identified by id.

visible Non-zero = visible (default); 0 = hidden (not rendered by wxbgi_render_dds).

wxbgi_dds_to_json()

BGI_API const char *BGI_CALL wxbgi_dds_to_json

(

void

)

Serialises the full DDS scene to a JSON string (DDJ format).

Returns a pointer to an internal thread-local buffer valid until the next call to any wxbgi_dds_to_* function from the same thread. The JSON is pretty-printed (2-space indent).

wxbgi_dds_to_yaml()

BGI_API const char *BGI_CALL wxbgi_dds_to_yaml

(

void

)

Serialises the full DDS scene to a YAML string (DDY format).

Returns a pointer to an internal thread-local buffer valid until the next call to any wxbgi_dds_to_* function from the same thread.

wxbgi_gl_pass_destroy()

BGI_API void BGI_CALL wxbgi_gl_pass_destroy

(

void

)

Release all OpenGL objects managed by the GL render pass.

Must be called with the GL context current and before destroying that context (e.g., from WxBgiCanvas destructor before deleting the wxGLContext). Safe to call when no GL pass was ever initialised (no-op in that case).

wxbgi_render_dds()

BGI_API void BGI_CALL wxbgi_render_dds

(

const char *

camName

)

Renders all visible DDS drawing objects through the named camera into the BGI pixel buffer.

ALL objects (BgiPixel, World3D, UcsLocal) are reprojected through the specified camera:

• BgiPixel coords are treated as world point (x, y, 0) and projected.
• World3D coords are projected directly.
• UcsLocal coords are transformed to world via their UCS, then projected.

Pass camName = NULL to use the active camera.

This function is fully implemented in Phase D. In Phase A–C it is a no-op (stub) so the header is stable from the start.

wxbgi_set_legacy_gl_render()

BGI_API void BGI_CALL wxbgi_set_legacy_gl_render

(

int

enable

)

Enable or disable the legacy per-pixel GL_POINTS rendering path.

When enable is non-zero, the page buffer is rendered using the old GL_POINTS loop (one glVertex2i per non-background pixel). When zero (default), a much faster texture-based path is used. The legacy path is provided only for backward-compatibility diagnostics.

wxbgi_solid_set_ambient()

BGI_API void BGI_CALL wxbgi_solid_set_ambient

(

float

a

)

Set the ambient light intensity (0–1).

Default: 0.20.

wxbgi_solid_set_diffuse()

BGI_API void BGI_CALL wxbgi_solid_set_diffuse

(

float

d

)

Set the diffuse light intensity (0–1).

Default: 0.70.

wxbgi_solid_set_fill_light()

BGI_API void BGI_CALL wxbgi_solid_set_fill_light	(	float	x,
		float	y,
		float	z,
		float	strength
	)

Set the secondary (fill) light direction and relative strength.

Default direction: (0, -1, 0); default strength: 0.3.

wxbgi_solid_set_light_dir()

BGI_API void BGI_CALL wxbgi_solid_set_light_dir	(	float	x,
		float	y,
		float	z
	)

Set the primary (key) light direction.

The vector is automatically normalised. Default: (-0.577, 0.577, 0.577).

wxbgi_solid_set_light_space()

BGI_API void BGI_CALL wxbgi_solid_set_light_space

(

int

worldSpace

)

Select light coordinate space.

Parameters

worldSpace

1 = world-space light (default), 0 = view-space light.

wxbgi_solid_set_specular()

BGI_API void BGI_CALL wxbgi_solid_set_specular	(	float	s,
		float	shininess
	)

Set the specular intensity and shininess exponent.

Defaults: specular = 0.30, shininess = 32.