Optional runtime/window/context helpers that complement classic BGI calls. More...

Collaboration diagram for Advanced OpenGL Extension API:

Modules
	User Input Hook Registration
	Register optional user-supplied callbacks that fire after the library has completed its own internal event processing.

	Mouse Scroll API
	Functions for reading accumulated scroll wheel input.

	Input Default-Behavior Control
	API for bypassing or re-enabling the library's built-in input processing.

	Hook-Context DDS Functions
	Functions safe to call from within user hook callbacks.

	PNG Export API
	Save the BGI framebuffer or a DDS camera view directly to a PNG file.

	wxWidgets Embedding API
	C API functions for hosting the BGI surface inside a wxGLCanvas.

	Standalone wx Window API
	wxPython-style App/Frame/MainLoop API for Python, Pascal, and simple C programs.

Functions
BGI_API int BGI_CALL	wxbgi_alloc_color (int r, int g, int b)
	Allocates the next free extended palette slot and assigns it an RGB colour.

BGI_API int BGI_CALL	wxbgi_begin_advanced_frame (float r, float g, float b, float a, int clearColor, int clearDepth)
	Begins a manual OpenGL frame.

BGI_API int BGI_CALL	wxbgi_define_color (int idx, int r, int g, int b)
	Assigns an RGB colour to a specific extended palette slot (index 16-255).

BGI_API int BGI_CALL	wxbgi_end_advanced_frame (int swapBuffers)
	Ends a manual frame.

BGI_API void BGI_CALL	wxbgi_free_color (int idx)
	Releases an extended palette slot so it may be reused by wxbgi_alloc_color.

BGI_API int BGI_CALL	wxbgi_get_framebuffer_size (int width, int height)
	Retrieves framebuffer size in physical pixels.

BGI_API const char *BGI_CALL	wxbgi_get_gl_string (int which)
	Returns OpenGL implementation strings.

BGI_API void BGI_CALL	wxbgi_get_mouse_pos (int x, int y)
	Returns the current mouse cursor position in window pixels.

BGI_API void *BGI_CALL	wxbgi_get_proc_address (const char *procName)
	Resolves an OpenGL function pointer by symbol name.

BGI_API double BGI_CALL	wxbgi_get_time_seconds (void)
	Returns the GLFW monotonic timer in seconds.

BGI_API int BGI_CALL	wxbgi_get_window_size (int width, int height)
	Retrieves window size in screen coordinates.

BGI_API void BGI_CALL	wxbgi_getrgb (int color, int r, int g, int *b)
	Retrieves the RGB components of any colour index (0-255).

BGI_API int BGI_CALL	wxbgi_is_key_down (int key)
	Queries whether a raw GLFW key code is currently held down.

BGI_API int BGI_CALL	wxbgi_is_ready (void)
	Checks whether advanced API operations can safely run.

BGI_API int BGI_CALL	wxbgi_key_pressed (void)
	Reports whether a translated keyboard key event is pending.

BGI_API int BGI_CALL	wxbgi_make_context_current (void)
	Makes the library OpenGL context current on this thread.

BGI_API int BGI_CALL	wxbgi_mouse_moved (void)
	Returns 1 if the mouse cursor moved since the last call to this function.

BGI_API int BGI_CALL	wxbgi_poll_events (void)
	Pumps pending OS/window events.

BGI_API int BGI_CALL	wxbgi_read_key (void)
	Reads the next translated keyboard event from the internal queue.

BGI_API int BGI_CALL	wxbgi_read_pixels_rgba8 (int x, int y, int width, int height, unsigned char *outBuffer, int outBufferSize)
	Reads RGBA8 pixels from the current framebuffer.

BGI_API void BGI_CALL	wxbgi_request_close (void)
	Requests closing the active graphics window.

BGI_API int BGI_CALL	wxbgi_set_vsync (int enabled)
	Enables or disables vertical synchronization.

BGI_API int BGI_CALL	wxbgi_set_window_title (const char *title)
	Updates the native window title text.

BGI_API int BGI_CALL	wxbgi_should_close (void)
	Reports whether the window received a close request.

BGI_API int BGI_CALL	wxbgi_swap_window_buffers (void)
	Swaps front/back window buffers immediately.

BGI_API int BGI_CALL	wxbgi_test_clear_key_queue (void)
	Optional internal test seam APIs.

BGI_API int BGI_CALL	wxbgi_test_inject_extended_scan (int scanCode)
	Internal test seam: injects an extended DOS-style key sequence.

BGI_API int BGI_CALL	wxbgi_test_inject_key_code (int keyCode)
	Internal test seam: injects one translated key code into the queue.

BGI_API int BGI_CALL	wxbgi_test_simulate_char (unsigned int codepoint)
	Test seam: simulate the full `charCallback` pipeline.

BGI_API int BGI_CALL	wxbgi_test_simulate_cursor (int x, int y)
	Test seam: simulate the full `cursorPosCallback` pipeline.

BGI_API int BGI_CALL	wxbgi_test_simulate_key (int key, int scancode, int action, int mods)
	Test seam: simulate the full `keyCallback` pipeline.

BGI_API int BGI_CALL	wxbgi_test_simulate_mouse_button (int button, int action, int mods)
	Test seam: simulate the full `mouseButtonCallback` pipeline.

BGI_API int BGI_CALL	wxbgi_test_simulate_scroll (double xoffset, double yoffset)
	Test seam: simulate the full `scrollCallback` pipeline.

BGI_API int BGI_CALL	wxbgi_write_pixels_rgba8 (int x, int y, int width, int height, const unsigned char *inBuffer, int inBufferSize)
	Writes RGBA8 pixels into the current framebuffer.

Detailed Description

Optional runtime/window/context helpers that complement classic BGI calls.

Function Documentation

◆ wxbgi_alloc_color()

BGI_API int BGI_CALL wxbgi_alloc_color	(	int	r,
		int	g,
		int	b
	)

Allocates the next free extended palette slot and assigns it an RGB colour.

Slots are assigned sequentially starting at index 16. Use wxbgi_free_color to release slots for reuse.

Parameters

r,g,b Colour components (0-255 each).

Returns: Allocated palette index (16-255), or -1 if all 240 extended slots are exhausted.

◆ wxbgi_begin_advanced_frame()

BGI_API int BGI_CALL wxbgi_begin_advanced_frame	(	float	r,
		float	g,
		float	b,
		float	a,
		int	clearColor,
		int	clearDepth
	)

Begins a manual OpenGL frame.

Optionally clears color and/or depth buffers, updates viewport to framebuffer dimensions, and polls events. This is intended for advanced rendering paths that mix custom GL with classic BGI drawing.

◆ wxbgi_define_color()

BGI_API int BGI_CALL wxbgi_define_color	(	int	idx,
		int	r,
		int	g,
		int	b
	)

Assigns an RGB colour to a specific extended palette slot (index 16-255).

The classic 16-colour BGI palette (indices 0-15) is unaffected; use the standard setrgbpalette for those entries.

Parameters

idx	Extended palette slot to define, must be in the range [16, 255].
r,g,b	Colour components (0-255 each).

Returns: idx on success, or -1 if idx is outside [16, 255].

◆ wxbgi_end_advanced_frame()

BGI_API int BGI_CALL wxbgi_end_advanced_frame ( int swapBuffers )

Ends a manual frame.

Flushes GL commands and optionally swaps buffers for presentation.

◆ wxbgi_free_color()

BGI_API void BGI_CALL wxbgi_free_color ( int idx )

Releases an extended palette slot so it may be reused by wxbgi_alloc_color.

The slot is reset to black (0,0,0). Has no effect on classic palette indices 0-15.

Parameters

idx	Extended palette slot to release (16-255).

◆ wxbgi_get_framebuffer_size()

BGI_API int BGI_CALL wxbgi_get_framebuffer_size	(	int *	width,
		int *	height
	)

Retrieves framebuffer size in physical pixels.

This can differ from window size on HiDPI displays.

◆ wxbgi_get_gl_string()

BGI_API const char *BGI_CALL wxbgi_get_gl_string ( int which )

Returns OpenGL implementation strings.

Parameters

which 0=vendor, 1=renderer, 2=version, 3=shading language version.

Returns: C string for requested token, or empty string on error.

◆ wxbgi_get_mouse_pos()

BGI_API void BGI_CALL wxbgi_get_mouse_pos	(	int *	x,
		int *	y
	)

Returns the current mouse cursor position in window pixels.

Writes the current mouse X and Y coordinates (in window pixels, origin top-left) into x and y. Either pointer may be NULL. Values are updated by GLFW's cursor-position callback; the function does not call glfwPollEvents() itself.

◆ wxbgi_get_proc_address()

BGI_API void *BGI_CALL wxbgi_get_proc_address ( const char * procName )

Resolves an OpenGL function pointer by symbol name.

Returns null when the symbol is unavailable in the active context.

◆ wxbgi_get_time_seconds()

BGI_API double BGI_CALL wxbgi_get_time_seconds ( void )

Returns the GLFW monotonic timer in seconds.

Useful for animation deltas, profiling, and frame timing.

◆ wxbgi_get_window_size()

BGI_API int BGI_CALL wxbgi_get_window_size	(	int *	width,
		int *	height
	)

Retrieves window size in screen coordinates.

Parameters

width	Receives current width.
height	Receives current height.

◆ wxbgi_getrgb()

BGI_API void BGI_CALL wxbgi_getrgb	(	int	color,
		int *	r,
		int *	g,
		int *	b
	)

Retrieves the RGB components of any colour index (0-255).

Works for both classic BGI palette entries (0-15, including any setrgbpalette overrides) and user-defined extended entries (16-255).

Parameters

color	Palette index 0-255.
r	Receives the red component (0-255).
g	Receives the green component (0-255).
b	Receives the blue component (0-255).

◆ wxbgi_is_key_down()

BGI_API int BGI_CALL wxbgi_is_key_down ( int key )

Queries whether a raw GLFW key code is currently held down.

Parameters

key	GLFW key code such as `GLFW_KEY_ESCAPE` or `GLFW_KEY_LEFT`.

Returns: 1 if the key is currently down, 0 if up, or -1 on invalid input.

This bypasses the translated queue and is useful for real-time key state checks alongside queued compatibility reads.

◆ wxbgi_is_ready()

BGI_API int BGI_CALL wxbgi_is_ready ( void )

Checks whether advanced API operations can safely run.

This returns 1 when a window/context exists and has not been closed, or 0 otherwise.

◆ wxbgi_key_pressed()

BGI_API int BGI_CALL wxbgi_key_pressed ( void )

Reports whether a translated keyboard key event is pending.

Returns 1 when wxbgi_read_key can consume a queued key, otherwise 0. Queue contents are generated from GLFW key and character callbacks attached to the active graphics window.

◆ wxbgi_make_context_current()

BGI_API int BGI_CALL wxbgi_make_context_current ( void )

Makes the library OpenGL context current on this thread.

Use this before raw OpenGL calls when your code can run across multiple threads.

◆ wxbgi_mouse_moved()

BGI_API int BGI_CALL wxbgi_mouse_moved ( void )

Returns 1 if the mouse cursor moved since the last call to this function.

The movement flag is set by the GLFW cursor-position callback and cleared each time this function is called. Use it to decide whether to redraw a frame that contains a mouse-tracking visual aid (e.g., the selection cursor).

Returns: 1 if the mouse moved since the previous call, 0 otherwise.

◆ wxbgi_poll_events()

BGI_API int BGI_CALL wxbgi_poll_events ( void )

Pumps pending OS/window events.

Call this in custom frame loops to keep input, resize, and close events responsive.

◆ wxbgi_read_key()

BGI_API int BGI_CALL wxbgi_read_key ( void )

Reads the next translated keyboard event from the internal queue.

Returns a non-negative key code when available, or -1 when no key is pending. Printable keys arrive as character codes. Special keys such as Escape, Enter, Tab, and Backspace are mapped to their classic control values. Extended keys follow DOS-style semantics by emitting 0 followed by the translated scan code on the next read.

◆ wxbgi_read_pixels_rgba8()

BGI_API int BGI_CALL wxbgi_read_pixels_rgba8	(	int	x,
		int	y,
		int	width,
		int	height,
		unsigned char *	outBuffer,
		int	outBufferSize
	)

Reads RGBA8 pixels from the current framebuffer.

This is useful for screenshots, pixel picking, and post-processing capture.

Returns: Number of bytes written, or a negative value on error.

◆ wxbgi_request_close()

BGI_API void BGI_CALL wxbgi_request_close ( void )

Requests closing the active graphics window.

This marks the window for shutdown so your loop can exit cleanly.

◆ wxbgi_set_vsync()

BGI_API int BGI_CALL wxbgi_set_vsync ( int enabled )

Enables or disables vertical synchronization.

Parameters

enabled Non-zero enables vsync, zero disables it.

◆ wxbgi_set_window_title()

BGI_API int BGI_CALL wxbgi_set_window_title ( const char * title )

Updates the native window title text.

Parameters

title UTF-8 title string.

◆ wxbgi_should_close()

BGI_API int BGI_CALL wxbgi_should_close ( void )

Reports whether the window received a close request.

Returns 1 when closing is pending, otherwise 0.

◆ wxbgi_swap_window_buffers()

BGI_API int BGI_CALL wxbgi_swap_window_buffers ( void )

Swaps front/back window buffers immediately.

This presents the back buffer to screen for custom rendering loops.

◆ wxbgi_test_clear_key_queue()

BGI_API int BGI_CALL wxbgi_test_clear_key_queue ( void )

Optional internal test seam APIs.

These APIs are compiled only when WXBGI_ENABLE_TEST_SEAMS is defined at build time. They are intended for deterministic CI/system testing and should never be enabled in public production/release builds.

Internal test seam: clears pending translated keyboard queue entries.

This is intended for automated tests only so CI can verify keyboard queue behavior without relying on host OS input injection.

◆ wxbgi_test_inject_extended_scan()

BGI_API int BGI_CALL wxbgi_test_inject_extended_scan ( int scanCode )

Internal test seam: injects an extended DOS-style key sequence.

Enqueues 0 followed by scanCode to mirror translated extended key reads.

◆ wxbgi_test_inject_key_code()

BGI_API int BGI_CALL wxbgi_test_inject_key_code ( int keyCode )

Internal test seam: injects one translated key code into the queue.

This bypasses GLFW callbacks and is intended for deterministic automated tests.

◆ wxbgi_test_simulate_char()

BGI_API int BGI_CALL wxbgi_test_simulate_char ( unsigned int codepoint )

Test seam: simulate the full charCallback pipeline.

Applies the same codepoint filter as charCallback (drops codepoints outside 1–255 and drops Tab/Enter/Escape without calling the hook), pushes accepted codepoints into keyQueue, then calls the registered userCharHook if set.

Parameters

codepoint Unicode codepoint to simulate (1–255 accepted).

Returns: 0 on success, -1 if no window is open.

◆ wxbgi_test_simulate_cursor()

BGI_API int BGI_CALL wxbgi_test_simulate_cursor	(	int	x,
		int	y
	)

Test seam: simulate the full cursorPosCallback pipeline.

Writes x / y into gState.mouseX / gState.mouseY, sets gState.mouseMoved = true, then calls the registered userCursorPosHook if set.

Parameters

x	New cursor X position in window pixels (top-left origin).
y	New cursor Y position in window pixels.

Returns: 0 on success, -1 if no window is open.

◆ wxbgi_test_simulate_key()

BGI_API int BGI_CALL wxbgi_test_simulate_key	(	int	key,
		int	scancode,
		int	action,
		int	mods
	)

Test seam: simulate the full keyCallback pipeline.

Updates gState.keyDown[key] (all actions), translates special/control keys into queue entries (press/repeat only), then calls the registered userKeyHook if set — faithfully replicating what keyCallback does without requiring a real GLFW key event.

Parameters

key	GLFW key constant (e.g. `GLFW_KEY_A` = 65).
scancode	OS scancode (passed to hook; not used for queue logic).
action	`WXBGI_KEY_PRESS`, `WXBGI_KEY_REPEAT`, or `WXBGI_KEY_RELEASE`.
mods	Modifier bitfield (e.g. `WXBGI_MOD_SHIFT`).

Returns: 0 on success, -1 if no window is open.

◆ wxbgi_test_simulate_mouse_button()

BGI_API int BGI_CALL wxbgi_test_simulate_mouse_button	(	int	button,
		int	action,
		int	mods
	)

Test seam: simulate the full mouseButtonCallback pipeline.

Calls the registered userMouseButtonHook if set. The DDS pick logic (overlayPerformPick) is intentionally omitted — it requires a valid rendered framebuffer that is not available in headless test contexts.

Parameters

button	Mouse button index (`WXBGI_MOUSE_LEFT`, etc.).
action	`WXBGI_KEY_PRESS` or `WXBGI_KEY_RELEASE`.
mods	Modifier bitfield.

Returns: 0 on success, -1 if no window is open.

◆ wxbgi_test_simulate_scroll()

BGI_API int BGI_CALL wxbgi_test_simulate_scroll	(	double	xoffset,
		double	yoffset
	)

Test seam: simulate the full scrollCallback pipeline.

Accumulates xoffset / yoffset into gState.scrollDeltaX/Y (if WXBGI_DEFAULT_SCROLL_ACCUM is active), then calls the registered userScrollHook if set — faithfully replicating what scrollCallback does.

Parameters

xoffset	Horizontal scroll delta.
yoffset	Vertical scroll delta (positive = up/forward).

Returns: 0 on success, -1 if no window is open.

◆ wxbgi_write_pixels_rgba8()

BGI_API int BGI_CALL wxbgi_write_pixels_rgba8	(	int	x,
		int	y,
		int	width,
		int	height,
		const unsigned char *	inBuffer,
		int	inBufferSize
	)

Writes RGBA8 pixels into the current framebuffer.

This replaces a rectangular region with caller-provided pixel data and is useful for texture-less blits, overlays, and framebuffer restore operations.

Returns: Number of bytes consumed, or a negative value on error.

Modules

Functions

Detailed Description

Function Documentation

◆ wxbgi_alloc_color()

◆ wxbgi_begin_advanced_frame()

◆ wxbgi_define_color()

◆ wxbgi_end_advanced_frame()

◆ wxbgi_free_color()

◆ wxbgi_get_framebuffer_size()

◆ wxbgi_get_gl_string()

◆ wxbgi_get_mouse_pos()

◆ wxbgi_get_proc_address()

◆ wxbgi_get_time_seconds()

◆ wxbgi_get_window_size()

◆ wxbgi_getrgb()

◆ wxbgi_is_key_down()

◆ wxbgi_is_ready()

◆ wxbgi_key_pressed()

◆ wxbgi_make_context_current()

◆ wxbgi_mouse_moved()

◆ wxbgi_poll_events()

◆ wxbgi_read_key()

◆ wxbgi_read_pixels_rgba8()

◆ wxbgi_request_close()

◆ wxbgi_set_vsync()

◆ wxbgi_set_window_title()

◆ wxbgi_should_close()

◆ wxbgi_swap_window_buffers()

◆ wxbgi_test_clear_key_queue()

◆ wxbgi_test_inject_extended_scan()

◆ wxbgi_test_inject_key_code()

◆ wxbgi_test_simulate_char()

◆ wxbgi_test_simulate_cursor()

◆ wxbgi_test_simulate_key()

◆ wxbgi_test_simulate_mouse_button()

◆ wxbgi_test_simulate_scroll()

◆ wxbgi_write_pixels_rgba8()