More info to come.
You can find small, contained samples of Kelpo in use under the examples/ directory.
It may be best to start by examining the
simple_triangle example. It does nothing but render a single static triangle, and so strips away everything except the bare essentials needed to incorporate Kelpo into an application.
You can find the full source code to Kelpo in the src/ directory.
The Kelpo codebase is split into three categories:
Renderer code is found under src/kelpo_renderer/.
A renderer represents a 3D API wrapped by Kelpo; e.g. Direct3D 7. It includes rasterizing and window management functionality using that API, and compiles into a standalone DLL library to be bundled with a client application (an application that uses Kelpo).
All Kelpo renderers provide the function
export_interface(), defined in the corresponding
renderer_xxxx.c source file found under src/kelpo_renderer/, which exports the renderer's code into a client application (see interface).
Client applications don't include renderer code directly, only the compiled renderer libraries (see interface)..
Exposed functions in renderer code use the
Renderer code is further split into three sub-categories:
Rasterizer code is responsible for rendering polygons using rasterizing functionality provided by the API (e.g. OpenGL 1.1). Exposed functions in rasterizer code use the
kelpo_rasterizer_xxxx__ prefix, where "xxxx" is the API's name (e.g. "opengl_1_1").
Window code provides the means to create and manage a Win32 window in which rasterized images can be displayed to the user. Exposed functions in window code use the
Surface code mediates between the rasterizer and the window, providing the rasterizer a surface to render into and inserting the surface into the window for display. (Some renderers rely on a combination of surfaces: for instance, the Direct3D 5 API requires by its design both a Direct3D and a DirectDraw surface.) Exposed functions in surface code use the
kelpo_surface_xxxx__ prefix, where "xxxx" is the API's name (e.g. "glide_3").
Interface code is found under src/kelpo_interface/.
Client applications include and use the interface code to interact with Kelpo's renderer libraries.
Interface code provides the
kelpo_interface_s struct populated via
kelpo_create_interface() with functions that allow a client application to operate a given Kelpo renderer.
Exposed functions in interface code use the
Auxiliary code is found under src/kelpo_auxiliary/.
Auxiliary code provides Kelpo-compatible implementations of various rendering-related tasks, e.g. triangle transformation. Client applications can optionally include some or all of this functionality to avoid having to implement it themselves.
Kelpo's auxiliary code is neither required by Kelpo to operate nor guaranteed to be best-case implementations. You can use it as a time saver or a starting point (minding any licensing restrictions), or choose to bring your own - it's up to you.
Exposed functions in auxiliary code use the
Every function exposed by the
kelpo_interface_s struct, as well as all internal Kelpo functions prefixed with
kelpo_, are guaranteed to return either 1 to indicate success or 0 to indicate failure.
Every such function that returns 0 will also push an error code into Kelpo's error queue, further describing the error. To retrieve these error codes, use the
To retrieve the most recent error code and remove it from the error queue, call
kelpo_error_code(). Calling this function in a loop until it returns
KELPOERR_ALL_GOOD will return and remove all errors in the queue, with
KELPOERR_ALL_GOOD indicating that the queue is empty.
To retrieve the most recent error code without modifying the error queue, call
kelpo_error_peek(). Since this function doesn't modify the queue, it can only return the most recent error, or
KELPOERR_ALL_GOOD if the queue is empty.
To find whether Kelpo has reported any errors - regardless of what those errors might be - you can use e.g.
(kelpo_error_peek() == KELPOERR_ALL_GOOD). It evaluates to true when there are no errors and false otherwise, without modifying the error queue.
The error queue can be reset (cleared) by calling
kelpo_error_reset(). All accumulated error codes will be removed, and both
kelpo_error_peek() will return
KELPOERR_ALL_GOOD until further errors are reported.