twix/raylib
1
0
Fork 0
mirror of https://github.com/raysan5/raylib.git synced 2025-12-25 10:22:33 -05:00
Code Issues Packages Projects Releases Wiki Activity

Created raylib syntax analysis (markdown)

Ray
2021-06-01 19:02:06 +02:00
parent 28acb929d1
commit bf2c74051b
1 changed files with 194 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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_