raylib syntax analysis

raylib is a simple and easy-to-use library to enjoy videogames programing... but, what makes the library simple and easy-to-use? Considering that for many users the first contact with the library is its API, 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, usually including word order.

To do this analysis a raylib.h parser has been created. That parser dissects API into small pieces; in the future it can also be useful for automatic docs and binding generation!

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

• Functions: Instructions called by the users to make things happen
• Structures (struct): Data types to organize information packages
• Enumerators (enum): Sequence of values for a specific type of data

Functions

Latest raylib version in the moment of this writing (3.8-dev) exposes a total of 470 functions, a relatively small API for a gamedev library.

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 rule make the API comprehensive, intuitive, easy-to-remember and easy-to-use.

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

1. Functions following a common pattern
2. Functions operating over specific type of data
3. Functions with unique pattern

1. Functions following a common pattern

Most of the functions of the library go into this first group (~360), there are some common <Action> that prepend the name of most of the functions:

pattern	function format	API count	examples
01	void Init*()	3	InitWindow(), InitAudioDevice(), InitAudioStream()
02	void Close*()	3	CloseWindow(), CloseAudioDevice(), CloseAudioStream()
03	void Begin*()	8	BeginDrawing(), BeginBlendMode()
04	void End*()	8	EndDrawing(), EndBlendMode()
05	TYPE Get*()	79	GetKeyPressed(), GetMouseX(), GetRayCollision*()
06	void Set*()	46	SetWindowTitle(), SetTargetFPS(), SetMouseScale()
07	bool Is*()	33	IsKeyPressed(), IsGamepadAvailable(), IsSoundPlaying()
08	TYPE Gen*()	20	GenImage*(), GenMesh*()
09	TYPE Load*()	33	LoadImage*(), LoadTexture*(), LoadSound*()
10	void Unload*()	21	UnloadImage(), UnloadTexture(), UnloadSound()
11	void Update*(, *)	8	UpdateTexture(), UpdateCamera()
12	bool Save*()	3	SaveFileData(), SaveFileText(), SaveStorageValue()
13	bool Export*()	5	ExportImage(), ExportImageAsCode(), ExportMesh(), ExportWave(), ExportWaveAsCode()
14	void Draw*()	79	DrawRectangle(), DrawTexture*(), DrawModel*()
15	bool CheckCollision*()	10	CheckCollisionRecs(), CheckCollisionCircles(), CheckCollisionBoxSphere()

2. Functions operating over specific type of data

Those functions 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:

pattern	function format	API count	examples
01	TYPE Color*()	7	ColorAlpha(), ColorFromHSV(), ColorToHSV()
02	Image/void Image*()	40	ImageFormat(), ImageCrop(), ImageResize(), ImageFlipVertical()
03	TYPE Text*()	16	TextFormat(), TextReplace(), TextSplit(), TextToLower()
04	Mesh*()	2	MeshTangents(), MeshBinormals()
05	Wave/void Wave*()	3	WaveFormat(), WaveCopy(), WaveCrop()

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

3. Functions with unique pattern

Remaining functions (43 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();
MaximizeWindow();
MinimizeWindow();
RestoreWindow();
ShowCursor();
HideCursor();
EnableCursor();
DisableCursor();
ClearBackground();
TakeScreenshot();
TraceLog();            // Not following pattern
MemAlloc();            // Data-type pattern?
MemRealloc();          // Data-type pattern?
MemFree();             // Data-type pattern?
FileExists();          // Not following pattern -> IsFileAvailable()?
DirectoryExists();     // Not following pattern -> IsDirectoryAvailable()?
ClearDirectoryFiles();
ChangeDirectory();
ClearDroppedFiles();
CompressData();
DecompressData();
OpenURL();

// textures.c
Fade();                // Left for backward compatibility, use ColorAlpha() instead

// text.c
MeasureText();
MeasureTextEx();
CodepointToUtf8();     // Not following pattern -> EncodeCodepointAsUtf8()?

// models.c
UploadMesh();

// raudio.c
PlaySound();
StopSound();
PauseSound();
ResumeSound();
PlaySoundMulti();
StopSoundMulti();
PlayMusicStream();
StopMusicStream();
PauseMusicStream();
ResumeMusicStream();
PlayAudioStream();
StopAudioStream();
PauseAudioStream();
ResumeAudioStream();

Functions naming

Most functions in raylib use a maximum of 4 words

Structures

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

num	struct name	fields count	comments
01	Vector2	2
02	Vector3	3
03	Vector4	4
04	Matrix	4
05	Color	4
06	Rectangle	4
07	Image	5
08	Texture	5
09	RenderTexture	3	2 words name
10	NPatchInfo	6	2 words name
11	CharInfo	5
12	Font	6
13	Camera3D	5
14	Camera2D	4
15	Mesh	15
16	Shader	2
17	MaterialMap	3	2 words name
18	Material	3
19	Transform	3
20	BoneInfo	2
21	Model	9
22	ModelAnimation	4	2 words name
23	Ray	2
24	RayCollision	4	2 words name
25	BoundingBox	2	2 words name
26	Wave	5
27	AudioStream	4	2 words name
28	Sound	2
29	Music	5
30	VrDeviceInfo	10	3 words name
31	VrStereoConfig	8	3 words name

Enumerations

num	enum name	values count	comments
01	ConfigFlags	14
02	TraceLogLevel	8	3 words name
03	KeyboardKey	110
04	MouseButton	8
05	MouseCursor	11
06	GamepadButton	18
07	GamepadAxis	6
08	MaterialMapIndex	11	3 words name
09	ShaderLocationIndex	26	3 words name
10	ShaderUniformDataType	9	4 words name
11	PixelFormat	21
12	TextureFilter	6
13	TextureWrap	4
14	CubemapLayout	6
15	FontType	3
16	BlendMode	6
17	Gestures	11
18	CameraMode	5
19	CameraProjection	2
20	NPatchLayout	3	3 words name