diff --git a/raylib-syntax-analysis.md b/raylib-syntax-analysis.md new file mode 100644 index 0000000..d82ffc2 --- /dev/null +++ b/raylib-syntax-analysis.md @@ -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: +``` + (); +``` +More specifically, every syntactic element implies: +``` + (); // 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 `` 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 ``. + +```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_ \ No newline at end of file