diff --git a/raylib-syntax-analysis.md b/raylib-syntax-analysis.md index 1ba8d1f..e0dbb7d 100644 --- a/raylib-syntax-analysis.md +++ b/raylib-syntax-analysis.md @@ -8,11 +8,11 @@ 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 + - **Enumerators (`enum`)**: Sequence of named values used for convenience ## 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. +Latest raylib version (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: ``` @@ -23,7 +23,7 @@ More specifically, every syntactic element implies: (); // Do an Action over some Object Attribute/State ``` -**Following this rule is what make the API comprehensive, intuitive, easy-to-remember and easy-to-use.** +**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 **3 groups**: @@ -37,21 +37,21 @@ Most of the functions of the library go into this first group **(359 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() +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 Check*()` | 10 | `CheckCollisionRecs()`, `CheckCollisionCircles()`, `CheckCollisionBoxSphere()` ### 2. Functions operating over specific type of data @@ -59,11 +59,11 @@ Those functions **(68 in total)** operate over a specific data type, so, it was 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() +01 | `TYPE Color*()` | 7 | `ColorAlpha()`, `ColorFromHSV()`, `ColorToHSV()` +02 | `Image Image*()`
`void Image*()` | **40** | `ImageFormat()`, `ImageCrop()`, `ImageResize()`,` ImageFlipVertical()` +03 | `TYPE Text*()` | **16** | `TextFormat()`, `TextReplace()`, `TextSplit()`, `TextToLower()` +04 | `Mesh*()` | 2 | `MeshTangents()`, `MeshBinormals()` +05 | `Wave Wave*()`
`void Wave*()` | 3 | `WaveFormat()`, `WaveCopy()`, `WaveCrop()` _NOTE: Maybe some of them are renamed in the future for consistency._ @@ -185,23 +185,23 @@ Most functions in raylib use a **maximum of 4 words** on its name. I think that' count| function | words | comments :--: | :----- | :---: | :---------- -001 | GetWindowScaleDPI() | 4 | _Acronym used_ -002 | GetWorldToScreenEx() | 5 | -003 | GetWorldToScreen2D() | 5 | -004 | GetScreenToWorld2D() | 5 | -005 | SetTargetFPS() | 5 | _Acronym used_ -006 | SetLoadFileDataCallback() | 5 | _Callback function_ -007 | SetSaveFileDataCallback() | 5 | _Callback function_ -008 | SetLoadFileTextCallback() | 5 | _Callback function_ -009 | SetSaveFileTextCallback() | 5 | _Callback function_ -010 | GetFileNameWithoutExt() | 5 | -011 | SetCameraSmoothZoomControl() | 5 | TODO: Review!!! -012 | ImageToPOT() | 3 | _Acronym used_ -013 | ImageRotateCCW() | 3 | _Acronym used_ -014 | ColorToHSV() | 3 | _Acronym used_ -015 | ColorFromHSV() | 3 | _Acronym used_ -016 | LoadMusicStreamFromMemory() | 5 | _*FromMemory() set of functions_ -017 | SetAudioStreamBufferSizeDefault() | **6** | **TODO: Review!!!** +001 | `GetWindowScaleDPI()` | 4 | _Acronym used_ +002 | `GetWorldToScreenEx()` | 5 | +003 | `GetWorldToScreen2D()` | 5 | +004 | `GetScreenToWorld2D()` | 5 | +005 | `SetTargetFPS()` | 5 | _Acronym used_ +006 | `SetLoadFileDataCallback()` | 5 | _Callback function_ +007 | `SetSaveFileDataCallback()` | 5 | _Callback function_ +008 | `SetLoadFileTextCallback()` | 5 | _Callback function_ +009 | `SetSaveFileTextCallback()` | 5 | _Callback function_ +010 | `GetFileNameWithoutExt()` | 5 | +011 | `SetCameraSmoothZoomControl()` | 5 | TODO: Review!!! +012 | `ImageToPOT()` | 3 | _Acronym used_ +013 | `ImageRotateCCW()` | 3 | _Acronym used_ +014 | `ColorToHSV()` | 3 | _Acronym used_ +015 | `ColorFromHSV()` | 3 | _Acronym used_ +016 | `LoadMusicStreamFromMemory()` | 5 | _*FromMemory() set of functions_ +017 | `SetAudioStreamBufferSizeDefault()` | **6** | **TODO: Review!!!** ### Functions parameters @@ -209,37 +209,37 @@ Most functions are limited to **5 or less input parameters**. I think 5 or less count| function | param count | comments :--: | :----- | :--: | :---------- -001 | SetCameraMoveControls() | 6 | -002 | DrawCircleSector() | 6 | -003 | DrawCircleSectorLines() | 6 | -004 | DrawRing() | 7 | _WARNING: >6 parameters_ -005 | DrawRingLines() | 7 | _WARNING: >6 parameters_ -006 | DrawRectangleGradientV() | 6 | -007 | DrawRectangleGradientH() | 6 | -008 | DrawPolyLinesEx() | 6 | -009 | GenImageChecked() | 6 | -010 | ImageResizeCanvas() | 6 | -011 | ImageDrawLine() | 6 | -012 | ImageDrawRectangle() | 6 | -013 | ImageDrawText() | 6 | -014 | ImageDrawTextEx() | 7 | _WARNING: >6 parameters_ -015 | DrawTextureTiled() | 7 | _WARNING: >6 parameters_ -016 | DrawTexturePro() | 6 | -017 | DrawTextureNPatch() | 6 | -018 | DrawTexturePoly() | 6 | -019 | LoadFontFromMemory() | 6 | -020 | LoadFontData() | 6 | -021 | GenImageFontAtlas() | 6 | -022 | DrawTextEx() | 6 | -023 | DrawTextRec() | 7 | _WARNING: >6 parameters_ -024 | DrawTextRecEx() | **11** | **TODO: Review!!!** -025 | DrawCubeTexture() | 6 | -026 | DrawCylinder() | 6 | -027 | DrawCylinderWires() | 6 | -028 | DrawModelEx() | 6 | -029 | DrawModelWiresEx() | 6 | -030 | DrawBillboardRec() | 6 | -031 | DrawBillboardPro() | 8 | _WARNING: >6 parameters_ +001 | `SetCameraMoveControls()` | 6 | +002 | `DrawCircleSector()` | 6 | +003 | `DrawCircleSectorLines()` | 6 | +004 | `DrawRing()` | 7 | _WARNING: >6 parameters_ +005 | `DrawRingLines()` | 7 | _WARNING: >6 parameters_ +006 | `DrawRectangleGradientV()` | 6 | +007 | `DrawRectangleGradientH()` | 6 | +008 | `DrawPolyLinesEx()` | 6 | +009 | `GenImageChecked()` | 6 | +010 | `ImageResizeCanvas()` | 6 | +011 | `ImageDrawLine()` | 6 | +012 | `ImageDrawRectangle()` | 6 | +013 | `ImageDrawText()` | 6 | +014 | `ImageDrawTextEx()` | 7 | _WARNING: >6 parameters_ +015 | `DrawTextureTiled()` | 7 | _WARNING: >6 parameters_ +016 | `DrawTexturePro()` | 6 | +017 | `DrawTextureNPatch()` | 6 | +018 | `DrawTexturePoly()` | 6 | +019 | `LoadFontFromMemory()` | 6 | +020 | `LoadFontData()` | 6 | +021 | `GenImageFontAtlas()` | 6 | +022 | `DrawTextEx()` | 6 | +023 | `DrawTextRec()` | 7 | _WARNING: >6 parameters_ +024 | `DrawTextRecEx()` | **11** | **TODO: Review!!!** +025 | `DrawCubeTexture()` | 6 | +026 | `DrawCylinder()` | 6 | +027 | `DrawCylinderWires()` | 6 | +028 | `DrawModelEx()` | 6 | +029 | `DrawModelWiresEx()` | 6 | +030 | `DrawBillboardRec()` | 6 | +031 | `DrawBillboardPro()` | 8 | _WARNING: >6 parameters_ Note that **only 7 function out of 470** require more than 6 parameters. This is what makes raylib so special. @@ -253,37 +253,37 @@ About the fields contained in every struct, it was tried to just include the min count | 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_ +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 @@ -293,27 +293,29 @@ Personally, I tried to avoid enum values requirement as much as possible within count | 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_ +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 | `Gesture` | 11 | +18 | `CameraMode` | 5 | +19 | `CameraProjection` | 2 | +20 | `NPatchLayout` | 3 | _3 words name_ ## Conclusion -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 name of each parameter, the data types required... This syntax analysis is a good way to see what worked for this library and how it can be improved. \ No newline at end of file +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 improved it. \ No newline at end of file