Skip to content

Latest commit

 

History

History
48 lines (29 loc) · 3.94 KB

DOCUMENTATION.md

File metadata and controls

48 lines (29 loc) · 3.94 KB

h-raylib documentation

This file only contains h-raylib specific information. For documentation on individual functions, check the raylib cheatsheet and the h-raylib Haddock documentation (incomplete). You can also look at the examples included here in the examples directory (written in Haskell), or you can look at the more extensive set of examples on the raylib website (written in C). For information about raylib in general, view the raylib wiki.

Memory management

Automatic management flow (recommended)

This flow is the one used in most of the example programs and should be used unless it is absolutely necessary not to.

  1. A WindowResources handle is retrieved by calling initWindow
  2. A load* function is called (e.g. loadModel) along with managed (e.g. model <- managed window $ loadModel filePath, where window :: WindowResources)
  3. The data is loaded
  4. Any data that requires extra functions be called to unload it is automatically stored in the WindowResources handle
  5. The window is closed and closeWindow is called with the WindowResources handle (closeWindow (Just window))
  6. All the data stored in the handle is now automatically unloaded

In some cases, models and other data used by a program are extremely large and thus expensive to keep in memory for the entire duration of the program. For this reason, the unload* functions are available to manually unload auto-managed data on the fly (be sure not to use the close function on automatically managed resources).

Make sure to take a look at the examples to get a better understanding of this.

Manual management flow

In some cases, you may want to opt out of automatic memory management, like so:

  1. initWindowUnmanaged is called (it does not return a WindowResources handle)
  2. A load* function is called without using managed (e.g. model <- loadModel filePath)
  3. The data is loaded
  4. The data must be manually unloaded with close (e.g. close model)
  5. The window is closed by calling closeWindow without a WindowResources handle (closeWindow Nothing)

Note that if you are using the automatic memory management flow, then you can still load unmanaged resources by simply omitting managed when loading something (e.g. model <- loadModel filePath); however, you will still have to unload it manually with close, just like in the manual management flow.

The Raylib.Internal module is available for advanced users who want to create their own WindowResources object and manually add resources to it. This should be used with caution; it is error-prone, and in the vast majority of cases, simply using the automatic or manual management flows is sufficient.

Project structure

h-raylib contains bindings for raylib.h, raymath.h, rcamera.h, rlgl.h, and raygui.h. The public modules' documentation can be found in Haddock, as mentioned above, and documentation for the private modules can be found in the source files.

Public modules

The binding functions in h-raylib are an almost one-to-one mapping to their corresponding raylib functions. The types and functions are, in some cases, slightly modified if it is possible to utilize Haskell features.

The initWindow function (Raylib.Core) returns a WindowResources value that must be passed to the managed function for automatic memory management.

(Most) functions that took a pointer as an argument in C were changed to take a regular type as an argument and return an updated version of the argument (there are a few exceptions, because Ptrs are difficult to avoid in some cases).

You can also access the underlying C functions by prepending c' to the function name (e.g. c'initWindow). This may be necessary for performance reasons. Note that if you do this, you will have to manually unload and free everything.