mirror of
https://github.com/raysan5/raylib.git
synced 2026-01-31 11:19:18 -05:00
Created raylib syntax analysis (markdown)
Ray
194
raylib-syntax-analysis.md
Normal file
194
raylib-syntax-analysis.md
Normal file
@ -0,0 +1,194 @@
|
|||||||
|
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](https://github.com/raysan5/raylib/tree/master/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<TYPE>*() | 20 | GenImage*(), GenMesh*()
|
||||||
|
09 | TYPE Load<TYPE>*() | **33** | LoadImage*(), LoadTexture*(), LoadSound*()
|
||||||
|
10 | void Unload<TYPE>*(<TYPE>) | 21 | UnloadImage(), UnloadTexture(), UnloadSound()
|
||||||
|
11 | void Update<TYPE>*(<TYPE>, *) | 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>`.
|
||||||
|
|
||||||
|
```c
|
||||||
|
// 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_
|
||||||
Reference in New Issue
Block a user