Metal

https://www.sylvain-huet.com/rsc/metal/doc/
Admin
Metal is a 3D graphics and programming language providing APIs for rendering, standard libraries for...
Tokens:47,279
Snippets:718
Trust Score:7.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### soundRecStart Function

Source: https://www.sylvain-huet.com/rsc/metal/doc/soundRecStart.html

Starts the audio recording process with specified parameters. Note that only one recording can be active at a time.

```APIDOC
## soundRecStart

### Description
Starts the audio recording process.

### Method
fun

### Parameters
#### Path Parameters
- **_nchannels_** (I) - Required - Number of recording channels (1 or 2).
- **_rate_** (I) - Required - Sampling frequency.
- **_resolution_** (I) - Required - Number of bits for recorded values (8 or 16).
- **_nbbuf_** (I) - Required - Number of recording buffers.
- **_len_** (I) - Required - Size in bytes of the buffers.

### Return Value
- **0** - Success
- **nil** - Failure

### Remarks
Attention, only one recording can be started at a time.

### See Also
soundRecStop, soundRecCbData
```

--------------------------------

### soundPlayStart Function

Source: https://www.sylvain-huet.com/rsc/metal/doc/soundPlayStart.html

Starts audio playback with specified channel, rate, resolution, buffer count, and buffer size.

```APIDOC
## soundPlayStart

### Description
Starts audio playback.

### Parameters
- **_nchannels_** (I) - Number of playback channels (1 or 2).
- **_rate_** (I) - Sampling rate.
- **_resolution_** (I) - Number of bits for read values (8 or 16).
- **_nbbuf_** (I) - Number of playback buffers.
- **_len_** (I) - Size in bytes of the buffers.

### Return Value
Returns 0 on success, nil on failure.

### See Also
soundPlayStop, soundPlayCbData, soundPlayCbClose, soundPlayVolume
```

--------------------------------

### camStart

Source: https://www.sylvain-huet.com/rsc/metal/doc/camStart.html

Starts a video capture. Creates a Cam element, returning nil if an error occurs. Errors can happen if the camera is already in use or if the bitmap size is not a recognized format.

```APIDOC
## camStart

### Description
Starts a video capture from a specified camera.

### Parameters
#### Path Parameters
- **number** (number) - Required - The camera number (index in camList).
- **bitmap** (bitmap) - Required - The bitmap to capture into (determines size).
- **callback** (fun [Cam] I) - Required - The callback function called for each captured frame.
- **framerate** (number) - Required - The framerate in milliseconds (may not work reliably).

### Return Value
- **Cam** - Creates a Cam element, or nil if an error occurs.

### Errors
- Camera is already in use.
- Bitmap size is not a recognized format by the camera.

### See Also
- camStop
```

--------------------------------

### listswitchstr Example

Source: https://www.sylvain-huet.com/rsc/metal/doc/listswitchstr.html

Demonstrates how to use listswitchstr to find a value associated with a string pattern in a list of tuples. The search is case-sensitive.

```Metal
listswitchstr ["x" 123]::["y" 456]::nil "x"
```

--------------------------------

### bitmapToBitmapAdd

Source: https://www.sylvain-huet.com/rsc/metal/doc/bitmapToBitmapAdd.html

Performs a copy of a region from the source bitmap to the destination bitmap, performing an 'addition' operation component by component, with saturation at 255. For example, the sum of pixels 0xff8000 and 0xff8000 results in 0xffff00.

```APIDOC
## bitmapToBitmapAdd

### Description
Performs a copy of a region from the source bitmap to the destination bitmap, performing an 'addition' operation component by component, with saturation at 255.

### Parameters
#### Path Parameters
- **_destination_** (Bitmap) - Required - The destination bitmap.
- **_xdest_** (I) - Required - The 'x' coordinate of the destination.
- **_ydest_** (I) - Required - The 'y' coordinate of the destination.
- **_source_** (Bitmap) - Required - The source bitmap.
- **_xsrc_** (I) - Required - The 'x' coordinate of the source.
- **_yscr_** (I) - Required - The 'y' coordinate of the source.
- **_width_** (I) - Optional - The width of the region to copy. If nil, the width of the source bitmap is considered.
- **_height_** (I) - Optional - The height of the region to copy. If nil, the height of the source bitmap is considered.

### Return Value
(Bitmap) - The bitmap passed as a parameter.
```

--------------------------------

### mp3eProcess

Source: https://www.sylvain-huet.com/rsc/metal/doc/mp3eProcess.html

Encodes WAV data into MP3 format. This function takes an MP3 encoder, the source WAV data, an index to start encoding from, and an optional length of data to encode.

```APIDOC
## mp3eProcess

### Description
Encodes WAV data into MP3 format.

### Parameters
#### Path Parameters
- **`_mp3e_`** (MP3 Encoder) - Required - The MP3 encoder instance.
- **`_src_`** (WAV Data Source) - Required - The source of the WAV data to be encoded.
- **`_index_`** (Integer) - Required - The starting index of the data in the source.
- **`_len_`** (Integer) - Optional - The size of the data in the source. If nil, all data from the index is used.

### Return Value
- **Encoded Data** (Bytes) - The resulting MP3 encoded data.
```

--------------------------------

### listend Function

Source: https://www.sylvain-huet.com/rsc/metal/doc/listend.html

Calculates and returns the portion of a list starting from a given index. The first element is at index 0. If the index is out of bounds, it returns nil or the original list as appropriate.

```APIDOC
## listend

### Description
Calcule la fin de la liste. Retourne la liste après le n-ieme élément. Le premier élément a pour index '0'.

### Parameters
- **`_list_`** (_list_) - Une liste quelconque.
- **`_index_`** (_integer_) - Un entier quelconque.

### Return Value
Retourne la liste après le n-ieme élément.

### Remarks
- `listend l 0 == tl l`
- `(listend l nil) -> nil`
- `(listend l (-1)) -> l`
- La fonction retourne nil si l'index est plus grand que le nombre d'éléments de la liste.

### See Also
- `listnth`
- `tl`
```

--------------------------------

### execSend Function Signature

Source: https://www.sylvain-huet.com/rsc/metal/doc/execSend.html

This function sends data from a string to the standard input of an executable. It takes the executable, the string data, and the starting index as parameters. It returns the index of the next byte to be sent, which is the size of the string if all data was transmitted successfully. The function is blocking and returns only after at least one byte has been sent or an error occurs.

```APIDOC
## execSend

### Description
Sends data to the standard input of an executable. Data from the string `_str_` is sent starting from the index `_index_`. The function does not necessarily send the entire string after `_index_`; it returns the index of the next byte to send (which is equal to the size of `_str_` if the function managed to transmit everything).

### Parameters
#### Path Parameters
- `_exec_` (Executable) - Required - Any executable.
- `_str_` (String) - Required - A string of characters.
- `_index_` (Integer) - Required - An integer, less than the size of the string `_str_`.

### Return Value
- (Integer) - An integer, less than the size of the string `_str_`.

### Remarks
This function is blocking: it only returns if it has managed to send at least one byte, or if there is an error (the executable has closed its standard input, which generally means it has finished).

### See Also
- `execRead`
- `execStart`
```

--------------------------------

### execStart

Source: https://www.sylvain-huet.com/rsc/metal/doc/execStart.html

Launches an executable asynchronously.

```APIDOC
## execStart

### Description
Launches an executable asynchronously.

### Parameters
#### Path Parameters
- **_cmd_** (string) - Required - The command line to execute.

### Return Value
- **Exec element** - The resulting Exec element.

### See Also
- execRead
- execSend
```

--------------------------------

### listswitchlstr

Source: https://www.sylvain-huet.com/rsc/metal/doc/listswitchlstr.html

Searches for a sublist starting with a specific pattern string (case-sensitive). If found, it returns the remainder of that sublist.

```APIDOC
## listswitchlstr

### Description
Searches for a sublist within a list of lists where the first element of the sublist matches the provided pattern string (case-sensitive). If a match is found, the function returns the rest of that sublist.

### Parameters
#### Path Parameters
- `_list_` (list of lists of strings) - Required - The list of lists to search within.
- `_pattern_` (string) - Required - The string to match against the first element of the sublists.

### Return Value
Returns the remainder of the sublist if the pattern is found as the first element (case-sensitive). Otherwise, the behavior is not explicitly defined in the source.

### Example
```
listswitchlstr (("x"::"abc"::"def"::nil)::("y"::"123"::nil)::nil) "x"
```

### Result Example
```
"abc"::"def"::nil
```

### See Also
`listswitch`, `listswitchl`, `listswitchstr`, `listswitchstri`, `listswitchlstri`
```

--------------------------------

### Create and Initialize Table

Source: https://www.sylvain-huet.com/rsc/metal/doc/newtab.html

Creates a table of a specified length, initializing each element with a given value. Be cautious with mutable initialization values as they are passed by reference.

```Metal
tab u0
```

--------------------------------

### Correctly Initialize a 2D Table

Source: https://www.sylvain-huet.com/rsc/metal/doc/newtab.html

Demonstrates the correct way to initialize a 2D table to avoid issues with reference-based initialization. Each row is independently created.

```Metal
let newtab 3 nil -> m in
(	for i=0;i< 3 do set m.i=newtab 3 0;
	m
)
```

--------------------------------

### glPassThrough

Source: https://www.sylvain-huet.com/rsc/metal/doc/Librairie_OpenGL.html

Sends a feedback command to the feedback buffer.

```APIDOC
## glPassThrough

### Description
Sends a feedback command to the feedback buffer.

### Method
```
void glPassThrough(GLfloat token);
```

### Parameters
- **token** (GLfloat) - The token to be passed.
```

--------------------------------

### bitmapToBitmapMul

Source: https://www.sylvain-huet.com/rsc/metal/doc/bitmapToBitmapMul.html

Copies a specified region from a source bitmap to a destination bitmap, applying a component-wise multiplication operation. This operation results in a product of pixel values, for example, 0xffffff multiplied by 0xff8000 yields 0xff8000.

```APIDOC
## bitmapToBitmapMul

### Description
Performs a copy of a region from the _source_ bitmap to the _destination_ bitmap, applying a component-wise 'multiplication' operation. For example, the product of pixels 0xffffff and 0xff8000 results in 0xff8000.

### Parameters
#### Path Parameters
- **_destination_** (Bitmap) - Required - The destination bitmap.
- **_xdest_** (I) - Required - The 'x' coordinate of the destination.
- **_ydest_** (I) - Required - The 'y' coordinate of the destination.
- **_source_** (Bitmap) - Required - The source bitmap.
- **_xsrc_** (I) - Required - The 'x' coordinate of the source.
- **_yscr_** (I) - Required - The 'y' coordinate of the source.
- **_width_** (I) - Optional - The width of the region to copy. If nil, the width of the source bitmap is considered.
- **_height_** (I) - Optional - The height of the region to copy. If nil, the height of the source bitmap is considered.

### Return Value
(Bitmap) - The bitmap passed as a parameter.
```

--------------------------------

### windowCreate

Source: https://www.sylvain-huet.com/rsc/metal/doc/windowCreate.html

Creates a new parent window with specified dimensions, type, and title.

```APIDOC
## windowCreate

### Description
Creates a new parent window. This function allows for the creation of various window types, including normal, resizable, and frameless windows.

### Method
`windowCreate`

### Parameters
#### Path Parameters
- `_x_` (I) - Required - X-coordinate of the child window relative to the screen. This is the coordinate of the window's potential padding.
- `_y_` (I) - Required - Y-coordinate of the child window relative to the screen. This is the coordinate of the window's potential padding.
- `_width_` (I) - Required - Width of the child window. This is the width of the client area of the window.
- `_height_` (I) - Required - Height of the child window. This is the height of the client area of the window.
- `_type_` (I) - Required - Type of the window. Possible values are:
  - `WINDOW_NORMAL`: Normal window, fixed size, with title bar.
  - `WINDOW_RESIZE`: Resizable window, with title bar.
  - `WINDOW_NOMENU_RESIZE`: Resizable window, without title bar.
  - `WINDOW_NOMENU`: Fixed size window, without title bar.
- `_title_` (S) - Required - Title of the child window.

### Return Value
**Window** - The newly created window.
```

--------------------------------

### bitmapCreate

Source: https://www.sylvain-huet.com/rsc/metal/doc/bitmapCreate.html

Creates a new bitmap with the specified width and height. The content of the bitmap is not initialized.

```APIDOC
## bitmapCreate

### Description
Creates a new bitmap with the specified width and height. The content of the bitmap is not initialized.

### Signature
`bitmapCreate(width: I, height: I): Bitmap`

### Parameters
#### Path Parameters
- **width** (I) - Required - The width of the bitmap to create.
- **height** (I) - Required - The height of the bitmap to create.

### Return Value
- **Bitmap** - The newly created bitmap.

### Remarks
The content of the bitmap is not initialized.

### See Also
- `bitmapDestroy`
```

--------------------------------

### listoffiles

Source: https://www.sylvain-huet.com/rsc/metal/doc/listoffiles.html

Calculates the list of files in a directory. It takes a directory name as input and returns a list of full file paths.

```APIDOC
## listoffiles

### Description
Calculates the list of files in a directory. It takes a directory name as input and returns a list of full file paths.

### Parameters
#### Path Parameters
- **_dir_** (string) - Required - A directory name, possibly relative.

### Return Value
- **list of strings** - Returns the list of full file names of the directory passed as a parameter.

### See Also
- listofsubdir
```

--------------------------------

### tcpSend Function

Source: https://www.sylvain-huet.com/rsc/metal/doc/tcpSend.html

Sends data over a TCP connection. It attempts to send all subsequent bytes starting from the specified index. If all bytes are sent successfully, it returns the buffer size. For large data transfers, it might send only a portion and return the index of the next byte to be transmitted. If an error occurs or if the buffer or connection is nil, it returns nil.

```APIDOC
## tcpSend

### Description
Envoi de données sur une connexion Tcp.

### Parameters
#### Path Parameters
- **connection** (Tcp) - Required - Une connexion Tcp.
- **buffer** (S) - Required - Une chaîne contenant les données à transmettre.
- **index** (I) - Required - L'index du premier octet de la chaîne à transmettre.

#### Return Value
- **index** (I) - Returns the index of the next byte to transmit, or nil if there was an error during transmission (or if buffer or connection are nil).

### Remarks
La fonction essaie d'envoyer tous les octets suivants _index_. S'il y arrive, il retourne la taille de _buffer_. Si les données envoyées sont en grand nombre, la connexion Tcp n'enverra que quelques octets, et la fonction retournera une valeur inférieure à la taille de buffer, correspondant à l'index du prochain octet à transmettre.
Si la fonction retourne nil, il ne faut pas oublier de fermer la connexion par un appel à `tcpClose`.

### See Also
- `tcpOpen`
- `tcpClose`
```

--------------------------------

### soundPlayCbData

Source: https://www.sylvain-huet.com/rsc/metal/doc/soundPlayCbData.html

Defines the playback callback, which is called each time the system needs the next audio buffer. The result of the callback should be the content of the next buffer to be played.

```APIDOC
## soundPlayCbData

### Description
Defines the playback callback, which is called each time the system needs the next audio buffer. The result of the callback should be the content of the next buffer to be played.

### Parameters
#### Path Parameters
- **Callback de lecture [numéro_buffer]** (function) - Required - The callback function that provides the next audio buffer.

### Return Value
- **0** (integer) - Indicates success.

### See Also
- `soundPlayStart`
- `soundPlayStop`
- `soundPlayCbClose`
- `soundPlayVolume`
```

--------------------------------

### oggCreate

Source: https://www.sylvain-huet.com/rsc/metal/doc/oggCreate.html

Instantiates an Ogg decoder. The decoder operates on a complete stream and cannot be updated with partial input. The number of samples returned is not the number of bytes; in stereo, a sample consists of two values and thus comprises 4 bytes.

```APIDOC
## oggCreate

### Description
Instantiates an Ogg decoder.

### Parameters
#### Path Parameters
- **_src_** (Ogg I I I) - Required - Content in Ogg format.

### Return Value
Returns a tuple [decoder nb_channels frequency nb_de_samples].

### Remarks
The Ogg decoder works on a complete string. It is not possible in this implementation to complete the incoming stream. The number of samples returned is not the number of bytes; in stereo, a sample consists of two values and thus comprises 4 bytes.

### See Also
- oggRead
- oggDestroy
- Ogg
```

--------------------------------

### mp3Create

Source: https://www.sylvain-huet.com/rsc/metal/doc/mp3Create.html

Creates an MP3 decoding structure.

```APIDOC
## mp3Create

### Description
Creates an MP3 decoding structure.

### Return Value
MP3 Decoder
```

--------------------------------

### Constructing Tag Name

Source: https://www.sylvain-huet.com/rsc/metal/doc/tagName.html

Shows how to create a tag object with a specified name.

```APIDOC
## Construct Tag

### Description
Constructs a tag object with a given name.

### Method
Constructor

### Endpoint
`[tagName:n]`

### Parameters
#### Path Parameters
- **n** (string) - Required - The desired name for the new tag.

### Response
#### Success Response (200)
- **Tag** (Tag) - A newly constructed tag object with the specified name.
```

--------------------------------

### windowShow Function

Source: https://www.sylvain-huet.com/rsc/metal/doc/windowShow.html

Displays the window passed as a parameter. If the window is nil or has been destroyed, the call is ignored.

```APIDOC
## windowShow

### Description
Displays the window passed as a parameter. If the window is nil or has been destroyed, the call is ignored.

### Parameters
#### Path Parameters
- **_window_** (Window) - Required - Any window.

### Return Value
- **Window** - The window passed as a parameter.

### Remarks
If the window is nil or has been destroyed, the call to this function is ignored.
```

--------------------------------

### mp3eCreate

Source: https://www.sylvain-huet.com/rsc/metal/doc/mp3eCreate.html

Creates an MP3 encoder based on the Lame library. It takes several parameters to configure the encoding process.

```APIDOC
## mp3eCreate

### Description
Creates an MP3 encoder (based on Lame).

### Parameters
#### Path Parameters
- **_bitrate_** (I) - Required - Bitrate of the MP3 stream (e.g., 128 for 128 kbits).
- **_nbchan_** (I) - Required - Number of channels (mono=1, stereo=2).
- **_freqin_** (I) - Required - Sampling frequency of the source.
- **_freqout_** (I) - Required - Sampling frequency of the compressed data.
- **_quality_** (I) - Required - Quality setting (2=good, 7=low).
- **_preset_** (I) - Required - Preset setting (refer to Lame documentation; 0=parameter ignored).
- **_opti_** (I) - Required - Assembler optimization (refer to Lame documentation; 0=parameter ignored).

### Return Value
- **MP3e** - An MP3 encoder object.

### See Also
- `MP3e`
- `mp3eDestroy`
- `mp3eProcess`
```

--------------------------------

### udpCreate

Source: https://www.sylvain-huet.com/rsc/metal/doc/udpCreate.html

Creates a UDP socket, optionally binding it to a local address and port. A callback function can be provided to handle incoming messages.

```APIDOC
## udpCreate

### Description
Creates a UDP socket, optionally binding it to a local address and port. A callback function can be provided to handle incoming messages.

### Method
fun [Udp S S] I

### Parameters
#### Path Parameters
- **_addr_** (string | nil) - Optional - Local address to assign to the UDP socket. Can be a port number (e.g., "80"), an IP address and port (e.g., "IP:port"), or nil to use any available port for sending only.
- **_callback_** (function) - Optional - A callback function that is invoked when the UDP socket receives a message. The callback receives the message content (S) and the sender's address (S) in "ip:port" format.

### Return Value
- **Udp** - The newly created UDP socket.

### Remarks
The callback is called when the UDP socket receives a message. The first argument S is the message content, and the second argument S is the sender's address in the format "ip:port".

### See Also
- udpSendTo
- udpDestroy
```

--------------------------------

### Constructing a Tag with a sub-node list

Source: https://www.sylvain-huet.com/rsc/metal/doc/tagSub.html

This shows how to construct a tag where the list of sub-nodes is provided.

```APIDOC
## Constructing tagSub

### Description
Constructs a tag with a specified list of sub-nodes.

### Method
Constructor

### Endpoint
`[tagSub:l]`

### Parameters
#### Path Parameters
- **l** (list) - Required - The list of sub-nodes to assign to the tag.

### Request Example
```json
{
  "tagSub": [
    // list of sub-nodes to be assigned
  ]
}
```

### Response
#### Success Response (200)
- **Tag** - The constructed tag object.

### Response Example
```json
{
  "Tag": {
    "tagSub": [
      // list of sub-nodes
    ]
  }
}
```
```

--------------------------------

### tcpserverCreate

Source: https://www.sylvain-huet.com/rsc/metal/doc/tcpserverCreate.html

Creates a TCP server. The callback function is invoked when a client connects.

```APIDOC
## tcpserverCreate

### Description
Creates a TCP server. The callback function is invoked when a client connects.

### Parameters
#### Path Parameters
- **_addr_** (string) - Required - The address of the TCP server to create. This can be a port number (e.g., "80") or an IP address and port (e.g., "127.0.0.1:8080").
- **_callback_** (function) - Required - A callback function that is called when a client connects. It receives the newly created TCP connection as its second argument.

### Return Value
- **TcpServer** - The newly created TCP server object, or nil if an error occurred during creation (e.g., malformed parameters or port already in use).

### See Also
- tcpserverDestroy
```

--------------------------------

### save(content, file)

Source: https://www.sylvain-huet.com/rsc/metal/doc/save.html

Creates a file with the given content. If the file already exists, it will be overwritten. The file path can be relative.

```APIDOC
## save(content, file)

### Description
Creates a file with the given content. If the file already exists, it will be overwritten. The file path can be relative.

### Parameters
#### Path Parameters
- **content** (string) - Required - The string content to write to the file.
- **file** (string) - Required - The name of the file, potentially a relative path.

### Return Value
- **integer**: Returns 0 on success, -1 on error, or nil if any parameter is nil.
```

--------------------------------

### mglMakeCurrent

Source: https://www.sylvain-huet.com/rsc/metal/doc/Librairie_OpenGL.html

Makes a GL rendering context the current one.

```APIDOC
## mglMakeCurrent

### Description
Makes a GL rendering context the current one.

### Method
```
void mglMakeCurrent(void *context);
```

### Parameters
- **context** (void *) - A pointer to the GL rendering context.
```

--------------------------------

### soundRecCbData

Source: https://www.sylvain-huet.com/rsc/metal/doc/soundRecCbData.html

Defines the recording callback. This function receives the recorded data. The callback's return value is not used.

```APIDOC
## `soundRecCbData`

### Description
Defines the recording callback. This function receives the recorded data. The callback's return value is not used.

### Parameters
#### Callback Function (`_cb_`)
- **`_cb_`** (Callback Function) - Required - The callback function to be registered. It accepts recorded data, buffer number.
  - Signature: `fun [S I] I` where `S` is the recorded data and `I` is the buffer number.

### Return Value
- **`0`** - Indicates success.

### See Also
- `soundRecStart`
- `soundRecStop`
```

--------------------------------

### windowCbPaint

Source: https://www.sylvain-huet.com/rsc/metal/doc/windowCbPaint.html

Defines a callback that is called when the window content needs to be redrawn.

```APIDOC
## windowCbPaint

### Description
Defines a callback function that is invoked when the content of a window needs to be redrawn. This is useful for handling custom drawing logic within a window.

### Parameters
#### Path Parameters
- **_window_** (Window) - Required - The window for which the callback is being set.
- **_callback_** (Callback) - Required - The callback function to be executed when a redraw is needed.

### Return Value
- **Window** - The window that was passed as a parameter.

### Remarks
- If the window is nil or has been destroyed, the function call is ignored.
- If the callback is nil, 'key pressed' events will no longer be transmitted to the window.
```

--------------------------------

### glTexEnvi

Source: https://www.sylvain-huet.com/rsc/metal/doc/Librairie_OpenGL.html

Sets a texturing environment parameter.

```APIDOC
## glTexEnvi

### Description
Sets a texturing environment parameter.

### Method
```
void glTexEnvi(GLenum target, GLenum pname, GLint param);
```

### Parameters
- **target** (GLenum) - Specifies the texture environment. Must be GL_TEXTURE_ENV.
- **pname** (GLenum) - Specifies the symbolic name of the texture environment parameter to be set. Common values include GL_TEXTURE_ENV_MODE.
- **param** (GLint) - Specifies the value of the parameter.
```

--------------------------------

### mglSwapBuffers

Source: https://www.sylvain-huet.com/rsc/metal/doc/Librairie_OpenGL.html

Swaps the front and back buffers.

```APIDOC
## mglSwapBuffers

### Description
Swaps the front and back buffers.

### Method
```
void mglSwapBuffers();
```
```

--------------------------------

### Constructing a Tag with Sub-nodes

Source: https://www.sylvain-huet.com/rsc/metal/doc/tagSub.html

Use this syntax to construct a tag where 'l' represents the list of sub-nodes.

```Metal
[tagSub:l]
```

--------------------------------

### Construct Tag with Attributes

Source: https://www.sylvain-huet.com/rsc/metal/doc/tagAttrib.html

Use `[tagAttrib:l]` to construct a tag where `l` is the list of attributes. This allows you to create a tag with a predefined set of attribute names and values.

```Metal
[tagAttrib:l]
```

--------------------------------

### bitmapFromFile

Source: https://www.sylvain-huet.com/rsc/metal/doc/bitmapFromFile.html

Reads a graphics file and creates a bitmap corresponding to its content. Supports BMP, GIF, JPEG, and PNG formats.

```APIDOC
## bitmapFromFile

### Description
Reads a graphics file and creates a bitmap corresponding to its content. Supports BMP, GIF, JPEG, and PNG formats. For animated GIFs, only the first frame is processed.

### Method
`bitmapFromFile`

### Parameters
#### Path Parameters
- **_file_** (string) - Required - The name of a file containing an image in a recognized format. This name can be absolute or relative.

### Return Value
- **Bitmap** - A new bitmap containing the image. Returns nil if an error occurs (e.g., file does not exist or is not a recognized format).

### Remarks
Supported formats include:
- Monochrome BMP
- 8-bit paletted BMP
- 24-bit BMP
- GIF (only the first image of an animated GIF is used; see `bitmapFromGif` for full animated GIF handling)
- JPEG
- PNG

### See Also
- `bitmapFromGif`
```

--------------------------------

### soundPlayVolume

Source: https://www.sylvain-huet.com/rsc/metal/doc/soundPlayVolume.html

Sets the left and right playback volume. It returns the value of the left volume.

```APIDOC
## soundPlayVolume

### Description
Sets the left and right playback volume. The function returns the value of the left volume.

### Parameters
#### Path Parameters
- **Volume gauche** (integer) - Required - Volume for the left channel, ranging from 0 to 65535.
- **Volume droit** (integer) - Required - Volume for the right channel, ranging from 0 to 65535.

### Return Value
- **Volume gauche** (integer) - The set volume for the left channel.
```

--------------------------------

### windowCbMove

Source: https://www.sylvain-huet.com/rsc/metal/doc/windowCbMove.html

Defines a callback function that is invoked when the window's position changes. The callback receives the new X and Y coordinates of the top-left corner, including padding.

```APIDOC
## windowCbMove

### Description
Defines a callback function that is invoked when the window's position changes. The callback receives the new X and Y coordinates of the top-left corner, including padding.

### Parameters
#### Path Parameters
- **_window_** (Window) - Required - Represents any window.
- **_callback_** (Callback) - Required - The callback function to be invoked.

### Return Value
- **Window** - The window passed as a parameter.

### Remarks
If the window is nil or has been destroyed, the function call is ignored. If the callback is nil, 'key down' events will no longer be sent to the window.
```

--------------------------------

### oggeCreate

Source: https://www.sylvain-huet.com/rsc/metal/doc/oggeCreate.html

Creates an Ogg encoder with the specified number of channels, input frequency, and quality.

```APIDOC
## oggeCreate

### Description
Crée un encodeur ogg.

### Parameters
#### Path Parameters
- **_nbchan** (I) - Required - Nombre de canaux (mono=1 stereo=2)
- **_freqin** (I) - Required - Fréquence d'échantillonnage de la source
- **_quality** (I) - Required - Qualité, en dixième (0=faible 10=bon)

### Return Value
#### Success Response
- **Ogge** - Un encodeur ogg
```

--------------------------------

### windowCreateChild

Source: https://www.sylvain-huet.com/rsc/metal/doc/windowCreateChild.html

Creates a child window. A child window corresponds to an area of its parent window, as opposed to a 'popup' window which appears above its parent window.

```APIDOC
## windowCreateChild

### Description
Creates a child window. A child window corresponds to an area of its parent window, as opposed to a 'popup' window which appears above its parent window.

### Parameters
#### Path Parameters
- **_father_** (Window) - Required - The parent window.
- **_x_** (I) - Required - The 'x' coordinate of the child window relative to its parent. This is the coordinate of the potential window padding.
- **_y_** (I) - Required - The 'y' coordinate of the child window relative to its parent. This is the coordinate of the potential window padding.
- **_width_** (I) - Required - The width of the child window. This is the width of the client area of the window.
- **_height_** (I) - Required - The height of the child window. This is the height of the client area of the window.
- **_type_** (I) - Required - The type of the child window (CHILD_NORMAL or CHILD_BORDER).

### Return Value
- **Window** - The newly created child window.

### See Also
- windowCreatePopup
```

--------------------------------

### windowSetPlacement

Source: https://www.sylvain-huet.com/rsc/metal/doc/windowSetPlacement.html

Redefines the placement of the window passed as a parameter. To keep a coordinate unchanged, simply pass nil as the argument.

```APIDOC
## windowSetPlacement

### Description
Redefines the placement of the window passed as a parameter. To keep a coordinate unchanged, simply pass nil as the argument.

### Method
`windowSetPlacement`

### Parameters
#### Path Parameters
- **_window_** (Window) - Required - Any window.
- **_x_** (I) - Required - X-coordinate of the child window relative to its parent. This is the coordinate of the window's potential padding.
- **_y_** (I) - Required - Y-coordinate of the child window relative to its parent. This is the coordinate of the window's potential padding.
- **_width_** (I) - Required - Width of the child window. This is the width of the window's client area.
- **_height_** (I) - Required - Height of the child window. This is the height of the window's client area.

### Return Value
- **Window** - The window passed as a parameter.
```

--------------------------------

### getcurrentdir

Source: https://www.sylvain-huet.com/rsc/metal/doc/getcurrentdir.html

Reads the current directory. Returns the current logical directory of the virtual machine. This is always a full path.

```APIDOC
## getcurrentdir

### Description
Reads the current directory. Returns the current logical directory of the virtual machine. This is always a full path.

### Return Value
- Returns the current logical directory of the virtual machine as a full path.

### See Also
- `setcurrentdir`
```

--------------------------------

### load Function

Source: https://www.sylvain-huet.com/rsc/metal/doc/load.html

Reads the content of a file. Returns nil if the file cannot be read.

```APIDOC
## load

### Description
Reads the content of a file. Returns nil if the file cannot be read.

### Parameters
#### Path Parameters
- **_file_** (string) - Required - The name of the file, possibly relative.

### Return Value
- **content** (string) - The content of the file passed as a parameter.
- **nil** - Returned if the file cannot be read.
```

--------------------------------

### windowCreatePopup

Source: https://www.sylvain-huet.com/rsc/metal/doc/windowCreatePopup.html

Creates a popup window. A popup window appears above its parent window, unlike a child window which corresponds to an area of its parent window.

```APIDOC
## windowCreatePopup

### Description
Creates a popup window. A popup window appears above its parent window, unlike a child window which corresponds to an area of its parent window.

### Parameters

#### Path Parameters
- **father** (Window) - Required - Parent window.
- **x** (I) - Required - 'x' coordinate of the child window relative to its parent. This is the coordinate of the possible window padding.
- **y** (I) - Required - 'y' coordinate of the child window relative to its parent. This is the coordinate of the possible window padding.
- **width** (I) - Required - Width of the child window. This is the width of the client area of the window.
- **height** (I) - Required - Height of the child window. This is the height of the client area of the window.
- **type** (I) - Required - Type of the popup window, to choose between:
  - WINDOW_NORMAL: Normal window, fixed size, with title bar
  - WINDOW_RESIZE: Resizable window, with title bar
  - WINDOW_NOMENU_RESIZE: Resizable window, without title bar
  - WINDOW_NOMENU: Fixed size window, without title bar
- **title** (S) - Required - Title of the child window.

### Return Value
The newly created popup window.
```

--------------------------------

### bitmapH

Source: https://www.sylvain-huet.com/rsc/metal/doc/bitmapH.html

Returns the height of a bitmap.

```APIDOC
## bitmapH

### Description
Returns the height of a bitmap.

### Parameters
#### Path Parameters
- **_bitmap_** (Bitmap) - Required - Any bitmap.

### Return Value
- **Height** (Integer) - The height of the bitmap (nil if the bitmap is nil or already destroyed).

### See Also
- bitmapW
```

--------------------------------

### copyfile

Source: https://www.sylvain-huet.com/rsc/metal/doc/copyfile.html

Copies a file from a source path to a destination path.

```APIDOC
## copyfile

### Description
Copie le fichier _filesrc_ sous le nom _filedst_

### Parameters
#### Path Parameters
- **_filesrc_** (S) - Required - Un nom de fichier éventuellement relatif.
- **_filedst_** (S) - Required - Un nom de fichier éventuellement relatif.

### Return Value
- **0** (I) - Indicates success.
```

--------------------------------

### bitmapFromTab

Source: https://www.sylvain-huet.com/rsc/metal/doc/bitmapFromTab.html

Recopies into a bitmap a table of RGB values, in the classic screen scan order: from left to right, then top to bottom.

```APIDOC
## bitmapFromTab

### Description
Recopies into a bitmap a table of RGB values, in the classic screen scan order: from left to right, then top to bottom.

### Parameters
#### Path Parameters
- **_bitmap_** (Bitmap) - Required - Any bitmap.
- **tab I** (Array) - Required - An array of integers containing exactly the number of pixels of the bitmap passed as a parameter.

### Return Value
- **Bitmap** - The bitmap passed as a parameter.

### See Also
- bitmapToTab
```

--------------------------------

### windowCbClick

Source: https://www.sylvain-huet.com/rsc/metal/doc/windowCbClick.html

Defines a callback function that is invoked when a click occurs within the window. The callback receives the X and Y coordinates of the click, along with the mouse button pressed (0 for left, 1 for right). Coordinates are relative to the top-left corner of the window's client area.

```APIDOC
## windowCbClick

### Description
Defines a callback function that is invoked when a click occurs within the window. The callback receives the X and Y coordinates of the click, along with the mouse button pressed (0 for left, 1 for right). Coordinates are relative to the top-left corner of the window's client area.

### Parameters
- **`_window_`** (Window) - The window for which to set the callback.
- **`_callback_`** (fun [Window I I I] I) - The callback function to be executed on click events.

### Return Value
- **Window** - The window that was passed as a parameter.

### Remarks
- If the window is nil or has been destroyed, the function call is ignored.
- If the callback is nil, 'key pressed' events will no longer be transmitted to the window.
```

--------------------------------

### Construct Tag with Name

Source: https://www.sylvain-huet.com/rsc/metal/doc/tagName.html

Use `[tagName:n]` to construct a tag whose name is `n`. This syntax is used for creating tags with predefined names.

```text
[tagName:n]
```

--------------------------------

### bitmapErase

Source: https://www.sylvain-huet.com/rsc/metal/doc/bitmapErase.html

Efface la totalité de la bitmap avec la couleur passé en paramètre.

```APIDOC
## bitmapErase

### Description
Efface la totalité de la bitmap avec la couleur passé en paramètre.

### Parameters
#### Path Parameters
- **_bitmap_** (Bitmap) - Required - N'importe quelle bitmap.
- **_color_** (I) - Required - Une couleur RGB.

### Return Value
- **Bitmap** - La bitmap passée en paramètre.
```

--------------------------------

### windowCbClose

Source: https://www.sylvain-huet.com/rsc/metal/doc/windowCbClose.html

Defines a callback function to be executed when a 'close' event is received by the specified window. If the callback returns a non-zero or non-nil value, the window will be closed by the system. Otherwise, the close request is ignored. If the window is nil or destroyed, the call is ignored. If the callback is nil, 'close' events will no longer be sent to the window.

```APIDOC
## windowCbClose

### Description
Defines a callback called when a 'close' event is received by the window passed as a parameter. A 'close' event generally corresponds to a closure requested by the user (e.g., by clicking the close button in the title bar). If the callback returns something other than 0 or nil, the window will effectively be closed by the system; otherwise, the close request will be ignored.

### Parameters
*   **`_window_`** (Window) - The window for which to set the close callback.
*   **`_callback_`** (Callback) - The callback function to be invoked on a 'close' event.

### Return Value
Returns the window passed as a parameter.

### Remarks
If the window is nil or has been destroyed, the call to this function is ignored. If the callback is nil, 'close' events will no longer be transmitted to the window.

### See Also
windowCbDestroy
```

--------------------------------

### soundRecStop

Source: https://www.sylvain-huet.com/rsc/metal/doc/soundRecStop.html

Stops the current audio recording. It returns 0 upon successful execution.

```APIDOC
## soundRecStop

### Description
Arrête l'enregistrement audio.

### Method
N/A (Function Call)

### Parameters
None

### Return Value
- **0** (integer) - Always returns 0, indicating success.

### See Also
- `soundRecStart`
- `soundRecCbData`
```

--------------------------------

### windowCbDestroy

Source: https://www.sylvain-huet.com/rsc/metal/doc/windowCbDestroy.html

Defines a callback that is invoked when a 'destroy' event is received by the specified window. A 'destroy' event is transmitted when the window is actually destroyed by the system.

```APIDOC
## windowCbDestroy

### Description
Defines a callback that is invoked when a 'destroy' event is received by the specified window. A 'destroy' event is transmitted when the window is actually destroyed by the system.

### Parameters
* **`_window_`** (Window) - The window for which to set the destroy callback.
* **`_callback_`** (fun [Window] I) - The callback function to be invoked when the window is destroyed.

### Return Value
Returns the window passed as a parameter.

### Remarks
If the window is nil or has already been destroyed, the function call is ignored. If the callback is nil, 'close' events will no longer be transmitted to the window. In a window hierarchy, the order of 'destroy' events is: popup windows, then the parent window, then child windows.

### See Also
(No specific see also links provided in the source)
```

--------------------------------

### mp3Process Function

Source: https://www.sylvain-huet.com/rsc/metal/doc/mp3Process.html

Decodes MP3 data from a source. It takes a decoder, source data, an index, and an optional length as input. It returns the decoded data or nil if insufficient source data is provided. A note advises keeping the data size small (around 64KB) to avoid issues.

```APIDOC
## mp3Process

### Description
Decodes MP3 data from a source.

### Parameters
#### Path Parameters
- **mp3** (MP3 Decoder) - Required - The MP3 decoder.
- **src** (Source data) - Required - The source of the MP3 data to decode.
- **index** (Index) - Required - The index of the data within the source.
- **len** (Length) - Optional - The size of the data within the source (nil means all data from the index).

### Return Value
- **Decoded data** - The decoded data. Returns nil if there is not enough source data.

### Remarks
The size of the data to provide seems to cause problems in some cases, especially when the entire MP3 file is transmitted at once. It is recommended to keep a small size, around 64KB.
```

--------------------------------

### oggeProcess

Source: https://www.sylvain-huet.com/rsc/metal/doc/oggeProcess.html

Encodes WAV data into Ogg format. It takes the Ogg encoder, source WAV data, an index, and an optional length as input, returning the encoded data.

```APIDOC
## oggeProcess

### Description
Encodes WAV data into Ogg format.

### Parameters
#### Path Parameters
- **_ogge_** (Ogge) - Required - Encoder ogg
- **_src_** (Source) - Required - Source of WAV data to encode
- **_index_** (Index) - Required - Index of the data in the source
- **_len_** (Length) - Optional - Size of the data in the source (nil: all data from the index)

### Return Value
- **Encoded Data** (Data) - The encoded data.
```

--------------------------------

### setcurrentdir

Source: https://www.sylvain-huet.com/rsc/metal/doc/setcurrentdir.html

Sets the current working directory of the virtual machine. The directory name can be relative. Logical directory names must end with '/'.

```APIDOC
## setcurrentdir

### Description
Sets the current working directory of the virtual machine.

### Method
fun

### Parameters
#### Path Parameters
- **_dir_** (string) - Required - A logical directory name, possibly relative. Logical directory names must always end with the '/' character.

### Return Value
- **integer** - Returns 0 on success, -1 on error, nil if the parameter was nil.

### Remarks
Remember that a logical directory name always ends with the '/' character.

### See Also
getcurrentdir
```

--------------------------------

### glPopMatrix

Source: https://www.sylvain-huet.com/rsc/metal/doc/Librairie_OpenGL.html

Pops the top matrix from the matrix stack.

```APIDOC
## glPopMatrix

### Description
Pops the top matrix from the matrix stack.

### Method
```
void glPopMatrix();
```
```

--------------------------------

### glRenderMode

Source: https://www.sylvain-huet.com/rsc/metal/doc/Librairie_OpenGL.html

Sets the render mode.

```APIDOC
## glRenderMode

### Description
Sets the render mode.

### Method
```
GLint glRenderMode(GLenum mode);
```

### Parameters
- **mode** (GLenum) - Specifies the render mode. Must be GL_RENDER, GL_SELECT, or GL_FEEDBACK.
```
Tokens:
Raw