# naylib-wrapper Configuration Guide naylib-wrapper is a tool for generating Nim wrappers for raylib projects using the JSON output of raylib-parser. This guide will walk you through the process of using naylib-wrapper effectively. ## Getting Started To get the best results, follow these initial steps: 1. Use raylib-parser on the header file, but only pass the content between the C include guard. 2. Sometimes, you may need to clean up the generated JSON file manually, as raylib-parser can fail to parse preprocessor directives correctly (e.g., in rlgl.h). ## Input Structure naylib-wrapper requires the following input: 1. A JSON file defining the API (generated by raylib-parser) 2. A configuration file 3. (Optional) Nim code snippets for insertion into the final output ## Configuration File The configuration file has several sections that define how the wrapper will be generated. Here’s a breakdown: ### General This section defines basic settings: ```ini [General] apiDefinition = api/raylib.json cHeader = raylib.h namespacePrefix = rl ``` - `apiDefinition`: Path to the JSON definitions file - `cHeader`: C header file to be declared by the `header` pragma in Nim output - `namespacePrefix`: (Optional) Used to remove explicit namespacing from some symbols ### Snippets This section allows you to insert code fragments at specific points in the output: For example defining `moduleHeader` will insert code at the start of the module, such as compile pragmas for C source files. ```ini [Snippets] moduleHeader = snippets/raylib_header.nim afterEnums = """ template Diffuse*(_: typedesc[MaterialMapIndex]): untyped = Albedo template Specular*(_: typedesc[MaterialMapIndex]): untyped = Metalness """ afterObjects = snippets/raylib_aux.nim afterFuncs = snippets/raylib_types.nim moduleEnd = snippets/raylib_funcs.nim ``` Available keys: `moduleHeader`, `afterEnums`, `afterObjects`, `afterFuncs`, `moduleEnd` ### Type Handling Several sections control how different types are handled. The syntax for defining keys is as follows: - functionName/parameterName: For function parameters. - functionName: For return types. - objectName/fieldName: For struct fields. - objectName: For structs. #### OutParameters Declares parameters as `out T`: ```ini [OutParameters] CheckCollisionLines/collisionPoint LoadImageAnim/frames ``` #### ArrayTypes Translates types to `ptr UncheckedArray[T]`: ```ini [ArrayTypes] Font/recs Material/maps LoadImageColors LoadImagePalette SetWindowIcons/images DrawLineStrip/points ``` #### OpenArrayParameters Converts parameters to `openArray[T]` and generates wrapper functions: ```ini [OpenArrayParameters] SetWindowIcons/images DrawLineStrip/points DrawTriangleFan/points ``` #### HiddenRefParameters Hides pointer semantics by using the `.byref` pragma. ```ini [HiddenRefParameters] GetCameraForward/camera GetCameraUp/camera GetCameraRight/camera GetCameraViewMatrix/camera ``` #### TypeReplacements Allows manual type conversion in cases where C types don’t map well to Nim types: ```ini [TypeReplacements] Shader/locs: "ptr UncheckedArray[ShaderLocation]" GenImageFontAtlas/glyphRecs: "ptr ptr UncheckedArray[Rectangle]" SetTraceLogCallback/callback: TraceLogCallbackImpl ``` ### Symbol Control These sections control how symbols are handled in the output: #### IgnoredSymbols Specifies symbols to be omitted from the output: ```ini [IgnoredSymbols] ColorIsEqual TextCopy TextIsEqual ``` #### PrivateSymbols Prevents specific symbols from being made public: ```ini [PrivateSymbols] MaterialMap/texture Material/shader AudioStream/buffer FilePathList MemAlloc MemRealloc ``` #### ReadOnlyFields Creates read-only getters for specified fields: ```ini [ReadOnlyFields] Font/glyphCount Mesh/vertexCount ``` ### Function Handling These sections control how functions are processed: #### WrappedFuncs Specifies manually wrapped functions: ```ini [WrappedFuncs] InitWindow UpdateTexture UpdateTextureRec GetPixelColor ``` The C function will be made private and suffixed with `Impl` to prevent naming clashes. You can insert your wrapped function using the `afterFuncs` option. #### NilIfEmptyParameters Defines parameter handling for functions that accept nullable C strings or arrays. It automatically converts empty Nim strings or sequences to NULL pointers in C. ```ini [NilIfEmptyParameters] GuiSetTooltip/tooltip GuiIconText/text GuiGroupBox/text GuiLine/text ``` #### DiscardReturn Lists functions whose return values should be discarded automatically. This eliminates the need for the `.discardable` pragma. ```ini [DiscardReturn] GuiGroupBox GuiLine GuiPanel GuiScrollPanel ``` #### BoolReturn Specifies functions whose integer return values should be converted to boolean values in Nim. ```ini [BoolReturn] GuiWindowBox GuiButton GuiLabelButton GuiToggleSlider ``` #### FunctionOverloads and FuncOverloadSuffixes Handle function overloading: ```ini [FuncOverloadSuffixes] V Rec Ex Pro [FunctionOverloads] GetScreenToWorldRayEx GetWorldToScreenEx UpdateCameraPro DrawPixelV DrawLineV ``` The suffixes are removed in the order they appear. #### NoSideEffectsFuncs Marks functions with the `noSideEffect` pragma: ```ini [NoSideEffectsFuncs] CheckCollisionCircleLine UpdateModelAnimationBoneMatrices GenImageText GenImageFontAtlas GetMeshBoundingBox IsModelAnimationValid IsSoundReady IsMaterialReady ``` All other functions are assumed to have side effects. ### Special Cases #### MangledSymbols Useful for cases where C symbols clash with other includes. ```ini [MangledSymbols] ShowCursor CloseWindow LoadImage DrawText Rectangle ``` This requires manual modifications to the C source files. #### IncompleteStructs Defines opaque types with the `inCompleteStruct` pragma: ```ini [IncompleteStructs] rAudioBuffer rAudioProcessor ``` All other types are assumed to be complete structs. #### EnumValuePrefixes Defines prefixes to be removed from enum values: ```ini [EnumValuePrefixes] FLAG_ LOG_ KEY_ MOUSE_CURSOR_ ``` The prefixes are removed in the order they appear. #### TypePrefixes Type-specific prefixing is an adopted convention in C programming for organizing functions that operate on a particular data structure. ```ini [TypePrefixes] Float Vector2 Vector3 Vector4 Matrix Quaternion ``` The prefixes are removed from function names. ### Misc #### KeepNamespacePrefix The symbols defined in this section will not be altered by `namespacePrefix`. ```ini [ KeepNamespacePrefix ] rlBegin rlEnd rlglInit rlglClose ``` #### DistinctAliases Type aliases that become distinct. ```ini [ DistinctAliases ] Quaternion ``` The borrow pragma is used to allow field access.