Skip to content

config_guide.md

Latest commit

 

History

History
350 lines (252 loc) · 6.56 KB

config_guide.md

File metadata and controls

350 lines (252 loc) · 6.56 KB
Raw

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:

[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.

[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:

[OutParameters]
CheckCollisionLines/collisionPoint
LoadImageAnim/frames

ArrayTypes

Translates types to ptr UncheckedArray[T]:

[ArrayTypes]
Font/recs
Material/maps
LoadImageColors
LoadImagePalette
SetWindowIcons/images
DrawLineStrip/points

OpenArrayParameters

Converts parameters to openArray[T] and generates wrapper functions:

[OpenArrayParameters]
SetWindowIcons/images
DrawLineStrip/points
DrawTriangleFan/points

HiddenRefParameters

Hides pointer semantics by using the .byref pragma.

[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:

[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:

[IgnoredSymbols]
ColorIsEqual
TextCopy
TextIsEqual

PrivateSymbols

Prevents specific symbols from being made public:

[PrivateSymbols]
MaterialMap/texture
Material/shader
AudioStream/buffer
FilePathList
MemAlloc
MemRealloc

ReadOnlyFields

Creates read-only getters for specified fields:

[ReadOnlyFields]
Font/glyphCount
Mesh/vertexCount

Function Handling

These sections control how functions are processed:

WrappedFuncs

Specifies manually wrapped functions:

[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.

[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.

[DiscardReturn]
GuiGroupBox
GuiLine
GuiPanel
GuiScrollPanel

BoolReturn

Specifies functions whose integer return values should be converted to boolean values in Nim.

[BoolReturn]
GuiWindowBox
GuiButton
GuiLabelButton
GuiToggleSlider

FunctionOverloads and FuncOverloadSuffixes

Handle function overloading:

[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:

[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.

[MangledSymbols]
ShowCursor
CloseWindow
LoadImage
DrawText
Rectangle

This requires manual modifications to the C source files.

IncompleteStructs

Defines opaque types with the inCompleteStruct pragma:

[IncompleteStructs]
rAudioBuffer
rAudioProcessor

All other types are assumed to be complete structs.

EnumValuePrefixes

Defines prefixes to be removed from enum values:

[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.

[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.

[ KeepNamespacePrefix ]
rlBegin
rlEnd
rlglInit
rlglClose

DistinctAliases

Type aliases that become distinct.

[ DistinctAliases ]

Quaternion

The borrow pragma is used to allow field access.