raylib syntax analysis - raysan5/raylib GitHub Wiki

This analysis has been made on raylib 5.1-dev that exposes a total of 558 functions.

raylib is a simple and easy-to-use library to enjoy videogames programing... but, what makes the library simple and easy-to-use? For many users the first approach to the library is through its API, so, here it is a small analysis of the API from a syntactic point of view.

How are the functions structured? Which words are used? How many parameters are exposed? How intuitive is it to understand or even guess every function/structure/enum when required? Syntax is the set of rules, principles, and processes that govern the structure of sentences in a given language and defines how we understand it.

To do this analysis a raylib.h parser has been created. That parser dissects API into small pieces to automatize some parts of the analysis; actually, this parser can also be useful for automatic docs and bindings generation!

The analysis is organized in 3 parts, one for each API element analyzed:

• 1. Functions: Instructions called by the users to make things happen
• 2. Structures (struct): Data types to organize information packages
• 3. Enumerators (enum): Sequence of named values used for convenience

All raylib functions try to follow this syntactic structure:

    <Verb><Subject><Complement>();

More specifically, every syntactic element implies:

    <Action><Object><Attribute/State>();  // Do an Action over some Object Attribute/State

Following this syntactic structure is what make the API comprehensive, intuitive, easy-to-remember and easy-to-use.

Checking the available functions with more detail, they can be divided into 6 groups:

• 1.1. Functions following a common pattern
• 1.2. Functions operating over specific type of data
• 1.3. Functions with unique pattern
• 1.4. Functions suffixes
• 1.5. Functions naming
• 1.6. Functions parameters

Most of the functions of the library go into this first group (416 functions), there is some common <Action> that prepends the name of most of the functions:

Those functions (74 in total) operate over a specific data type, so, it was decided to prepend the DataType to the function name, they are an exception over the main syntax rule followed by the API:

NOTE: Maybe some of them are renamed in the future for consistency.

Remaining functions (57 in total) follow a unique pattern, still, most of them follow the standard syntax pattern of <Verb><Subject><Complement>.

// core.c
WindowShouldClose();   // Not following pattern
ClearWindowState();
ToggleFullscreen();
ToggleBorderlessWindowed();
MaximizeWindow();
MinimizeWindow();
RestoreWindow();
EnableEventWaiting();
DisableEventWaiting();
ShowCursor();
HideCursor();
EnableCursor();
DisableCursor();
ClearBackground();
SwapScreenBuffer();
PollInputEvents();
WaitTime();
TakeScreenshot();
TraceLog();            // Not following pattern
OpenURL();
MemAlloc();            // Data-type pattern?
MemRealloc();          // Data-type pattern?
MemFree();             // Data-type pattern?
FileExists();          // Not following pattern -> IsFileAvailable()?
DirectoryExists();     // Not following pattern -> IsDirectoryAvailable()?
ClearDirectoryFiles();
ChangeDirectory();
CompressData();
DecompressData();
EncodeDataBase64();
DecodeDataBase64();
StartAutomationEventRecording();
StopAutomationEventRecording();
PlayAutomationEvent();

// textures.c
Fade();                // Superseded by ColorAlpha()

// text.c
MeasureText();
MeasureTextEx();
CodepointToUTF8();     // Not following pattern -> EncodeCodepointAsUTF8()?

// models.c
UploadMesh();

// raudio.c
PlaySound();
StopSound();
PauseSound();
ResumeSound();
PlayMusicStream();
StopMusicStream();
PauseMusicStream();
ResumeMusicStream();
SeekMusicStream();
PlayAudioStream();
StopAudioStream();
PauseAudioStream();
ResumeAudioStream();
SeekAudioStream();
AttachAudioStreamProcessor();
DetachAudioStreamProcessor();
AttachAudioMixedProcessor();
DetachAudioMixedProcessor();

A part from the function prefixes that we can find in many functions names (1. common patterns), we can also find some common suffixes used by several functions:

// Suffix: *V() -> Used for "Vector" versions of same name functions
//------------------------------------------------------------------------------------------------
// rcore.c
void SetShaderValueV();
Vector2 GetMouseWheelMoveV();
// rshapes.c
void DrawPixelV();
void DrawLineV();
void DrawCircleV();
void DrawCircleLinesV();
void DrawRectangleV();
void DrawRectangleGradientV();
// rtextures.c
void ImageDrawPixelV();
void ImageDrawLineV();
void ImageDrawCircleV();
void ImageDrawRectangleV();
void DrawTextureV();
// rmodels.c
void DrawCubeV();
void DrawCubeWiresV();

// Suffix: *Ex() -> Used for "Extended" versions of same name functions
//------------------------------------------------------------------------------------------------
// rcore.c
Vector2 GetWorldToScreenEx();
// rshapes.c
void DrawLineEx();
void DrawRectangleGradientEx();
void DrawRectangleLinesEx();
void DrawPolyLinesEx();
// rtextures.c
Image ImageTextEx();
void ImageDrawTextEx();
void DrawTextureEx();
// rtext.c
Font LoadFontEx();
void DrawTextEx();
Vector2 MeasureTextEx();
// rmodels.c
void DrawSphereEx();
void DrawCylinderEx();
void DrawCylinderWiresEx();
void DrawModelEx();
void DrawModelWiresEx();

// Suffix: *Pro() -> Used for "Professional" versions of same name functions, more advanced than "Ex"
//------------------------------------------------------------------------------------------------
// rshapes.c
void DrawRectanglePro();
// rtextures.c
void DrawTexturePro();
// rtext.c
void DrawTextPro();
// rmodels.c
void DrawBillboardPro();

// Suffix: *Rec() -> Used for functions requiring a "Rectangle" as one main input parameter
//------------------------------------------------------------------------------------------------
// rshapes.c
void DrawRectangleRec();
bool CheckCollisionCircleRec();
bool CheckCollisionPointRec();
Rectangle GetCollisionRec();
// rtextures.c
void ImageDrawRectangleRec();
void UpdateTextureRec();
void DrawTextureRec();
// rtext.c
Rectangle GetGlyphAtlasRec();
// rmodels.c
void DrawBillboardRec();

// Suffix: *FromMemory() -> Used for functions loading data "from memory" instead of from files
//------------------------------------------------------------------------------------------------
Shader LoadShaderFromMemory();
Image LoadImageAnimFromMemory();
Image LoadImageFromMemory();
Font LoadFontFromMemory();
Wave LoadWaveFromMemory();
Music LoadMusicStreamFromMemory();

// Suffix: *Callback() -> Used for functions setting a callback function
//------------------------------------------------------------------------------------------------
void SetTraceLogCallback();
void SetLoadFileDataCallback();
void SetSaveFileDataCallback();
void SetLoadFileTextCallback();
void SetSaveFileTextCallback();
void SetAudioStreamCallback();

Most functions in raylib use a maximum of 4 words on its name. I think that's a good trade-off to remember the name of the function. Still, there is a small set of functions that go beyond that limit:

Most functions are limited to 5 or less input parameters. I think 5 or less parameters is a good number to keep the function simple and rememberable, more than 5 usually requires the user to use some kind of intellisense system. The number of parameters is a key point for raylib simplicity, still, there are some functions requiring 6 or more parameters:

Note that only 6 function out of 470 require more than 6 parameters. This is what makes raylib so special.

raylib defines a total of 34 struct data types, most of those structs use a single word to define the type and some of them use two words.

raylib tries to provide generic data types for most common use scenarios, only some of those structs are required for specific examples: NPatchInfo, VrDeviceInfo, VrStereoConfig.

About the fields contained in every struct, it was tried to just include the minimum required but when moving into 3d Mesh and Model, the amount of required data grows fast. For a more detailed analysis on data structures (not purely syntactic), check Wiki entry: raylib data structures.

raylib defines 21 enumerations for convenience. Enum names and contained value names are kept simple and clear. Most of those values are only required to be used by some very specific functions, for a detailed list check Wiki entry: raylib enumerated types.

Personally, I tried to avoid enum values requirement as much as possible within the library, actually, only 35 function in raylib could require using some enum value on some of its input parameters.

One of the goals of raylib is being simple and easy-to-use and many hours have been put into the API design; thinking about the best name for every function, the minimum number of parameters required, the right name of each parameter, the data types structure and more.

I think this syntax analysis is useful to see what worked for raylib library and also help to improve it.