# What is bound

Generated by `mix ex_mujoco.gen` from MuJoCo's own headers. Regenerating is
the only way to edit this page, and `mix ex_mujoco.gen --check` fails when it
disagrees with the headers.

## Functions

| MuJoCo functions | 551 |
| --- | --- |
| bound 1:1 by the generator | 25 |
| bound by hand | 13 |
| not bound | 513 |

### Bound by hand

These need a decision per call — an error buffer to allocate, an output array
whose length is the caller's business, a state signature — so they are written
out in `c_src/ex_mujoco_nif.cpp` rather than generated.

* `load_xml/1` — the error is a caller-sized char buffer; here it is our buffer and an exception
* `load_xml_string/1` — a parsed spec has to be compiled and freed around the model, which is a lifetime question
* `data/1` — the data block belongs to a model, so the handle holds both
* `reset/1` — the step surface is `(data)`, because the handle carries its model
* `forward/1` — same: `ExMujoco.forward/1` takes the data, not model and data
* `step/1` — same: `ExMujoco.step/1` takes the data
* `state_size/2` — paired with get_state and set_state, which share the signature's meaning
* `get_state/2` — writes into a buffer whose length `state_size` fixed; allocated here
* `set_state/3` — reads a buffer whose length `state_size` fixed; checked here
* `data_state_size/2` — the same count, asked of the data `put_state` is given
* `contact_force/2` — writes six numbers into a caller's array; allocated here
* `version/0` — the library's own version, checked against the headers at load time
* `header_version/0` — the header's version, for the same check

### Not bound

426 of MuJoCo's 551 functions take something a
NIF cannot honestly invent — a callback, a `void*`, an output array whose
length nothing states, a variadic argument list — and binding one means
deciding that question, one function at a time. The other
87
are expressible and simply not bound yet: a name in `c_src/manifest.exs`, and
`mix ex_mujoco.gen`.

Decisions worth naming:

* `mjSpec` — building a model at run time (mjs_addBody and the rest) is v0.2; loading XML, from a path or from a string, is enough to run anything meanwhile
* `mj_copyData` — it answers the destination it was given, and a handle to a data block you already hold is not a useful answer; copying state is `state/2` and `put_state/3`
* `mj_printData, mj_printModel` — they write into a buffer the caller sizes; a string-returning wrapper is a design decision, not a translation
* `mjrContext` — offscreen rendering is v0.3 — it needs a GL context per platform (EGL, OSMesa, CGL, WGL) and owns a thread

## Fields

| struct | scalars | arrays | not exposed |
| --- | --- | --- | --- |
| `mjModel` | 101 | 484 | 10 |
| `mjData` | 38 | 180 | 8 |

MuJoCo's own API reference describes each of them; the names and the units are
MuJoCo's, and its documentation is the documentation for the field.

## Enums

All 83 enums MuJoCo declares are generated into `ExMujoco.Types`
with the values resolved from the headers — including the ones C numbers
implicitly and the ones that are an OR of their siblings.