API & Extension Review

Table of Contents

• Potential Reviewers
• Status
  • Legend
  • Core
  • Extension
  • Libraries

Potential Reviewers

Before comfortably marking many of the existing APIs as 1.0, we'd like to get more eyes on them. At the moment the priority is NOT new features or implementation details. Many of these APIs are extremely minimal and that's on purpose and can be added to later.

Extendable

The 1st priority of these reviews is ensuring the APIs going into 1.0 do not box us in. An example of this could be something like this:

// initial design
plShaderModule pl_compile_glsl(const char* pcShader, const char* pcEntryFunc, bool bIncludeDebugInfo);

// better design
plShaderModule pl_compile_glsl(const char* pcShader, const char* pcEntryFunc, plShaderOptions*);

In this particular case, some obvious thought into the compiling shaders would have quickly revealed many additional parameters you may or may not want to add in the future. With the initial design, you would be forced to either break the API or add additional functions (further complicating the API). A better design in this case would be to pack options into a struct so additional members could be added in the future. This is not to say we should just have this apply to every function. Simplicity plays an important factor and if there truly is no foreseeable reason to need more parameters, then choose the simpler API.

The "tools" for adding additional functionality looks something like this (in order of preference):

1. Add additional flags
2. Add additional members to descriptor/options parameter
3. Add "extended" version function with new parameters pl_compile_glsl_ext(...)
4. Add new function

These are in order of preference.

Compacting

Another thing to consider is "compacting" an API. For example:

// typical memory allocation functions
void* pl_alloc(size_t);          // allocate new memory
void  pl_free(void*);            // free memory
void* pl_realloc(void*, size_t); // reallocate memory

If you spent some time considering this API, you'd realize the API can be simplified to just the pl_realloc(...). For reallocations, just use the function like expected. To free memory, pass in the pointer and a size of 0. To allocator for the first time, just pass NULL for the data and a size > 0:

// allocate new memory
int* iData = pl_realloc(NULL, 1024);

// reallocate memory
iData = pl_realloc(iData, 2048);

// free memory
pl_realloc(iData, 0);

This is a more compact design. For users who prefer the less compact design, that can easily be created on top with either macros, inline functions, or regular functions.

More examples will be added. Please open an issue to discuss any review items.

Status

Status Legend

The status symbols found below will be used throughout this document, but I will further explain them here.

Symbol	Description	Notes
✔️	1.0	API is stable (will not be broken) but can be added to
🟢	Review Needed	Candidate for 1.0. Just need more eyes on the API
🟡	Beta	Most of the API is stable but there are known changes needed
🔴	Active Development	API is under active development and subject to frequent changes
📝	Documentation Needed	This doesn't hold up 1.0
🚥	Tests Needed	This doesn't hold up 1.0

Core

The Core of Pilot Light is very small and entirely contained in the src directory. The Core APIs are split into 2 categories. The Base category APIs are provided in the pl.h header file and are required by any Pilot Light application. The OS category APIs are optional and provided by the pl_os.h header file. The current status of these APIs can be found in the table below:

	API	Status	Description
Base			platform agnostic systems
	API Registry	✔️ 📝 🚥
	Data Registry	✔️ 📝 🚥
	Extension Registry	✔️ 📝 🚥
	IO	✔️ 📝 🚥	keyboard + mouse + event input/output
	Memory	✔️ 📝 🚥	general memory allocator for tracking
OS			provided by OS backends
	Window	✔️ 📝 🚥	OS windowing
	Library	✔️ 📝 🚥	shared library loading (dlls/so files)
	File	✔️ 📝 🚥	simple file IO
	Network	✔️ 📝 🚥	UDP/TCP API
	Threads	✔️ 📝 🚥	basic thread & synchronization primitives
	Atomics	✔️ 📝 🚥	basic atomic primitives
	Virtual Memory	✔️ 📝 🚥	virtual memory access

Extension

If some functionality can be an extension, then it should be. Most of the real work is put into the extensions which are found in the extensions directory. The Standard extensions are those included directly in the Pilot Light code base. The current status of the APIs provided by these extensions can be found in the table below:

API	Status	File	Description
Image	✔️ 📝 🚥	pl_image_ext.h	image loading
Stats	✔️ 📝 🚥	pl_stats_ext.h	statistics
Rect Pack	✔️ 📝 🚥	pl_rect_pack_ext.h	rectangle packing
Job	✔️ 📝 🚥	pl_job_ext.h	basic job system
GPU Allocators	✔️ 📝 🚥	pl_gpu_allocators_ext.h	GPU allocators
Shader	✔️ 📝 🚥	pl_shader_ext.h	shader compiling
Draw	🟡 📝 🚥	pl_draw_ext.h	2D/3D drawing
UI	🟡 📝 🚥	pl_ui_ext.h	debug UI
ECS	🟡 📝	pl_ecs_ext.h
Model Loader	🟡 📝	pl_model_loader_ext.h	model loaders
Graphics	🟡 📝	pl_graphics_ext.h	graphics API abstraction over Vulkan & Metal 2.0
Draw Backend	🟡 📝	pl_draw_backend_ext.h	draw backend using pl_graphics_ext.h
Resource Manager	🔴 📝 🚥	pl_resource_ext.h	resource manager
Renderer	🔴 📝	pl_renderer_ext.h	reference renderer

Libraries

The Libraries are referring to the STB style libraries found in the libs directory. These are completely standalone libraries. The status of this can be seen below:

Library	Status	File	Description
Data Structures	✔️ 🚥	pl_ds.h	minimal data structures
JSON	✔️ 🚥	pl_json.h	JSON parser
Log	✔️ 🚥	pl_log.h	logger
Math	✔️ 🚥	pl_math.h	math
Memory	✔️ 🚥	pl_memory.h	memory allocators
Profiler	✔️ 🚥	pl_profile.h	profiler
STL	✔️ 🚥	pl_stl.h	STL File parser
String	✔️ 🚥	pl_string.h	string utilities
Testing	✔️	pl_test.h	minimal testing library