### Run bgfx Example

Source: https://bkaradzic.github.io/bgfx/examples.html

Execute a compiled bgfx example from the runtime directory.

```bash
<bgfx_path>/examples/runtime $ ../../.build/<config>/bin/example-00-helloworldDebug
```

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

### Quick start for Windows

Source: https://bkaradzic.github.io/bgfx/build.html

Commands to navigate to the directory, generate Visual Studio 2022 project files, and open the solution.

```bash
cd bgfx
```

```bash
..\bx\tools\bin\windows\genie --with-examples vs2022
```

```bash
start .build\projects\vs2022\bgfx.sln
```

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

### Install Linux dependencies

Source: https://bkaradzic.github.io/bgfx/build.html

Install required development headers for Linux builds.

```bash
sudo apt-get install libgl1-mesa-dev x11proto-core-dev libx11-dev
```

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

### Build macOS Release

Source: https://bkaradzic.github.io/bgfx/build.html

Use this command for a release build on macOS via the command line. Navigate to the examples/runtime directory to run the compiled examples.

```bash
make osx-release
cd examples/runtime
../../.build/osx64_clang/bin/examples.app/Contents/MacOS/examplesRelease
```

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

### Define Instance Buffer Attributes

Source: https://bkaradzic.github.io/bgfx/tools.html

Example of defining instance buffer inputs in varying.def.sc. Attributes must use vec4 types and specific TEXCOORD semantics.

```text
vec4 i_data0 : TEXCOORD7;
vec4 i_data1 : TEXCOORD6;
vec4 i_data2 : TEXCOORD5;
vec4 i_data3 : TEXCOORD4;
vec4 i_data4 : TEXCOORD3;
```

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

### Renderer Backend Information

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Provides functions to query the active rendering backend type and to get a list of supported renderers.

```APIDOC
## GET /renderer/supported

### Description
Retrieves a list of supported rendering backend APIs.

### Method
GET

### Endpoint
/renderer/supported

### Parameters
#### Query Parameters
- **_max** (uint8_t) - Optional - Maximum number of elements in the _enum array.
- **_enum** (RendererType::Enum[]) - Optional - Array where supported renderers will be written.

### Response
#### Success Response (200)
- **count** (uint8_t) - Number of supported renderers.
- **renderers** (RendererType::Enum[]) - Array of supported renderer types.

#### Response Example
```json
{
  "count": 3,
  "renderers": [
    "Direct3D11",
    "OpenGL",
    "Vulkan"
  ]
}
```

## GET /renderer/type

### Description
Queries the active rendering backend API type.

### Method
GET

### Endpoint
/renderer/type

### Response
#### Success Response (200)
- **type** (RendererType::Enum) - The current renderer backend API type.

#### Response Example
```json
{
  "type": "Direct3D11"
}
```
```

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

### Set Working Directory in Xcode

Source: https://bkaradzic.github.io/bgfx/build.html

Manually set the custom working directory for an Xcode project to ensure examples run correctly. This is necessary due to limitations in GENie's configuration for Xcode projects.

```bash
${PROJECT_DIR}/../../../examples/runtime
```

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

### Documentation Comments

Source: https://bkaradzic.github.io/bgfx/idl.html

Lines starting with `---` before a declaration become documentation comments, emitted as Doxygen-style comments or descriptions.

```APIDOC
## Documentation comments

### Description
Lines starting with `---` before a declaration become documentation comments. These are emitted as Doxygen-style comments in the C/C++ headers and as descriptions in the generated docs.

### Supported Doxygen Tags
* `@attention`
* `@warning`
* `@remarks`
* `@param`
* `@returns`

### Example
```
---
--- @attention `bgfx::renderFrame` is a blocking call.
---
--- @warning This call should only be used on platforms that don't
---   allow creating a separate rendering thread.
---
func.renderFrame { section = "Platform specific" }
    "RenderFrame::Enum"
    .msecs "int32_t"
    { default = -1 }
```
```

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

### Build using Makefile wrapper

Source: https://bkaradzic.github.io/bgfx/build.html

Use the convenience makefile to build the project or specific configurations.

```bash
cd bgfx
make
```

```bash
make <configuration>
```

```bash
linux-release64, wasm-debug, wasm-release, osx-debug, osx-release, android-arm64-release, etc.
```

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

### Build Windows via command line

Source: https://bkaradzic.github.io/bgfx/build.html

Build the Visual Studio 2022 release configuration from the command line.

```bash
make vs2022-release64
```

```bash
start .build\projects\vs2022\bgfx.sln
```

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

### GET bgfx::getStats()

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Retrieves the current performance counters for the renderer. The returned pointer is valid until the next call to bgfx::frame.

```APIDOC
## GET bgfx::getStats()

### Description
Returns the performance counters for the current frame. The returned pointer remains valid until the next call to bgfx::frame.

### Response
#### Success Response (200)
- **cpuTimeFrame** (int64_t) - CPU time between two bgfx::frame calls.
- **cpuTimeBegin** (int64_t) - Render thread CPU submit begin time.
- **cpuTimeEnd** (int64_t) - Render thread CPU submit end time.
- **cpuTimerFreq** (int64_t) - CPU timer frequency (timestamps-per-second).
- **gpuTimeBegin** (int64_t) - GPU frame begin time.
- **gpuTimeEnd** (int64_t) - GPU frame end time.
- **gpuTimerFreq** (int64_t) - GPU timer frequency.
- **waitRender** (int64_t) - Time spent waiting for render backend thread.
- **waitSubmit** (int64_t) - Time spent waiting for submit thread.
- **numDraw** (uint32_t) - Number of draw calls submitted.
- **numCompute** (uint32_t) - Number of compute calls submitted.
- **numBlit** (uint32_t) - Number of blit calls submitted.
- **maxGpuLatency** (uint32_t) - GPU driver latency.
- **gpuFrameNum** (uint32_t) - Frame which generated gpuTimeBegin/End.
- **numDynamicIndexBuffers** (uint16_t) - Number of used dynamic index buffers.
- **numDynamicVertexBuffers** (uint16_t) - Number of used dynamic vertex buffers.
- **numFrameBuffers** (uint16_t) - Number of used frame buffers.
- **numIndexBuffers** (uint16_t) - Number of used index buffers.
- **numOcclusionQueries** (uint16_t) - Number of used occlusion queries.
- **numPrograms** (uint16_t) - Number of used programs.
- **numShaders** (uint16_t) - Number of used shaders.
- **numTextures** (uint16_t) - Number of used textures.
- **numUniforms** (uint16_t) - Number of used uniforms.
- **numVertexBuffers** (uint16_t) - Number of used vertex buffers.
- **numVertexLayouts** (uint16_t) - Number of used vertex layouts.
- **textureMemoryUsed** (int64_t) - Estimate of texture memory used.
- **rtMemoryUsed** (int64_t) - Estimate of render target memory used.
- **transientVbUsed** (int32_t) - Amount of transient vertex buffer used.
- **transientIbUsed** (int32_t) - Amount of transient index buffer used.
- **numPrims** (uint32_t[]) - Number of primitives rendered.
- **gpuMemoryMax** (int64_t) - Maximum available GPU memory.
- **gpuMemoryUsed** (int64_t) - Amount of GPU memory used.
- **width** (uint16_t) - Backbuffer width.
- **height** (uint16_t) - Backbuffer height.
- **textWidth** (uint16_t) - Debug text width.
- **textHeight** (uint16_t) - Debug text height.
- **numViews** (uint16_t) - Number of view stats.
- **viewStats** (ViewStats*) - Array of View stats.
- **numEncoders** (uint8_t) - Number of encoders used.
- **encoderStats** (EncoderStats*) - Array of encoder stats.
```

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

### Build Tools with GENie

Source: https://bkaradzic.github.io/bgfx/build.html

Use the GENie tool with the `--with-tools` option to build project files that include bgfx's utility tools.

```bash
../bx/tools/bin/windows/genie --with-tools vs2022
```

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

### Build Linux Release

Source: https://bkaradzic.github.io/bgfx/build.html

Compile a 64-bit release build of bgfx for Linux using the make command.

```bash
make linux-release64
```

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

### Initialization and Shutdown

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Functions for initializing and shutting down the bgfx rendering system, along with constants for PCI IDs.

```APIDOC
## Initialization and Shutdown

### Description
Functions to initialize and shut down the bgfx rendering system.

### Functions
- `bgfx::Init` - Structure for initialization parameters.
- `init()` - Initializes the bgfx system.
- `shutdown()` - Shuts down the bgfx system.

### Constants
- `BGFX_PCI_ID_NONE`
- `BGFX_PCI_ID_SOFTWARE_RASTERIZER`
- `BGFX_PCI_ID_AMD`
- `BGFX_PCI_ID_APPLE`
- `BGFX_PCI_ID_INTEL`
- `BGFX_PCI_ID_NVIDIA`
- `BGFX_PCI_ID_MICROSOFT`
- `BGFX_PCI_ID_ARM`
```

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

### Build gmake projects

Source: https://bkaradzic.github.io/bgfx/build.html

Compile generated gmake projects using the specified configuration.

```bash
make config=<config> -C .build/projects/<platform>-gmake
```

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

### Vertex and Instance Configuration

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Methods to define vertex counts, instance data buffers, and instance counts for draw primitives.

```APIDOC
## setVertexCount

### Description
Set number of vertices for auto generated vertices use in conjunction with gl_VertexID.

### Parameters
#### Request Body
- **_numVertices** (uint32_t) - Required - Number of vertices.

## setInstanceDataBuffer

### Description
Set instance data buffer for draw primitive. Supports transient buffers, vertex buffers, and dynamic vertex buffers.

### Parameters
#### Request Body
- **_idb** (InstanceDataBuffer*) - Optional - Transient instance data buffer.
- **_start** (uint32_t) - Optional - First instance data.
- **_num** (uint32_t) - Optional - Number of data instances.
- **_handle** (VertexBufferHandle/DynamicVertexBufferHandle) - Optional - Vertex buffer handle.
- **_startVertex** (uint32_t) - Optional - First instance data.
```

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

### Geometry Compiler Usage

Source: https://bkaradzic.github.io/bgfx/tools.html

Basic command-line syntax for converting mesh files to the optimized bgfx format.

```bash
geometryc -f <in> -o <out>
```

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

### Clone bgfx and dependencies

Source: https://bkaradzic.github.io/bgfx/build.html

Clone the bx, bimg, and bgfx repositories as siblings in the same directory.

```bash
git clone https://github.com/bkaradzic/bx.git
git clone https://github.com/bkaradzic/bimg.git
git clone https://github.com/bkaradzic/bgfx.git
```

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

### Initialization and Shutdown API

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Provides functions for initializing and shutting down the bgfx library, along with related data structures and constants.

```APIDOC
## Initialization and Shutdown API

### Description
Functions and structures related to the initialization and shutdown of the bgfx library.

### Initialization Constants

- **BGFX_PCI_ID_NONE**: Autoselect adapter.
- **BGFX_PCI_ID_SOFTWARE_RASTERIZER**: Software rasterizer.
- **BGFX_PCI_ID_AMD**: AMD adapter.
- **BGFX_PCI_ID_APPLE**: Apple adapter.
- **BGFX_PCI_ID_INTEL**: Intel adapter.
- **BGFX_PCI_ID_NVIDIA**: nVidia adapter.
- **BGFX_PCI_ID_MICROSOFT**: Microsoft adapter.
- **BGFX_PCI_ID_ARM**: ARM adapter.

### Structures

#### `Resolution`

Backbuffer resolution and reset parameters.

- **formatColor** (TextureFormat::Enum) - Backbuffer color format.
- **formatDepthStencil** (TextureFormat::Enum) - Backbuffer depth/stencil format.
- **width** (uint32_t) - Backbuffer width.
- **height** (uint32_t) - Backbuffer height.
- **reset** (uint32_t) - Reset parameters.
- **numBackBuffers** (uint8_t) - Number of back buffers.
- **maxFrameLatency** (uint8_t) - Maximum frame latency.
- **debugTextScale** (uint8_t) - Scale factor for debug text.

#### `Init`

Initialization parameters used by `bgfx::init`.

- **type** (RendererType::Enum) - Select rendering backend. When set to `RendererType::Count` a default rendering backend will be selected appropriate to the platform. See: `bgfx::RendererType`.
- **vendorId** (uint16_t) - Vendor PCI ID. If set to `BGFX_PCI_ID_NONE`, discrete and integrated GPUs will be prioritised.
- **deviceId** (uint16_t) - Device ID. If set to 0 it will select first device, or device with matching ID.
- **capabilities** (uint64_t) - Capabilities initialization mask (default: UINT64_MAX).
- **debug** (bool) - Enable device for debugging.
- **profile** (bool) - Enable device for profiling.
- **fallback** (bool) - Enable fallback to next available renderer.
- **platformData** (PlatformData) - Platform data.
- **resolution** (Resolution) - Backbuffer resolution and reset parameters. See: `bgfx::Resolution`.
- **limits** (Limits) - Configurable runtime limits parameters.
- **callback** (CallbackI *) - Provide application specific callback interface. See: `bgfx::CallbackI`.
- **allocator** (bx::AllocatorI *) - Custom allocator. When a custom allocator is not specified, bgfx uses the CRT allocator. Bgfx assumes custom allocator is thread safe.

#### `Limits`

- **maxEncoders** (uint16_t) - Maximum number of encoder threads.
- **minResourceCbSize** (uint32_t) - Minimum resource command buffer size.
- **maxTransientVbSize** (uint32_t) - Maximum transient vertex buffer size.
- **maxTransientIbSize** (uint32_t) - Maximum transient index buffer size.
- **minUniformBufferSize** (uint32_t) - Minimum uniform buffer size.

### Functions

#### `bgfx::init`

Initialize the bgfx library.

- **_init** (const Init &) - Initialization parameters. See: `bgfx::Init` for more info.

Returns: `true` if initialization was successful.

#### `bgfx::shutdown`

Shutdown bgfx library.

```

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

### Configure OpenGL version

Source: https://bkaradzic.github.io/bgfx/build.html

Set the BGFX_CONFIG environment variable to specify a minimum OpenGL version before running GENie.

```bash
# Unix:
export BGFX_CONFIG=RENDERER_OPENGL_MIN_VERSION=40
# Windows:
set BGFX_CONFIG=RENDERER_OPENGL_MIN_VERSION=40

../bx/tools/bin/<platform>/genie <... your options ...>
```

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

### Add documentation comments

Source: https://bkaradzic.github.io/bgfx/idl.html

Uses Doxygen-style tags to provide documentation for API functions.

```bgfx-idl
--- Render frame.
---
--- @attention `bgfx::renderFrame` is a blocking call.
---
--- @warning This call should only be used on platforms that don't
---   allow creating a separate rendering thread.
---
func.renderFrame { section = "Platform specific" }
    "RenderFrame::Enum"
    .msecs "int32_t"
    { default = -1 }
```

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

### Define documentation sections

Source: https://bkaradzic.github.io/bgfx/idl.html

Organizes the API reference into a hierarchical structure.

```bgfx-idl
section("API Reference", 0)
section("General", 1)
section("Initialization and Shutdown", 2)
```

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

### Build WinRT/UWP Project

Source: https://bkaradzic.github.io/bgfx/build.html

Generate a Visual Studio project for WinRT/UWP targeting Windows 10 using the GENie tool. Ensure shaders are compiled with the appropriate target profile.

```bash
../bx/tools/bin/windows/genie --vs=winstore100 vs2022
```

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

### submit

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Submit primitive for rendering with index and instance data info and draw count from indirect buffers.

```APIDOC
## void submit(ViewId _id, ProgramHandle _program, IndirectBufferHandle _indirectHandle, uint32_t _start, IndexBufferHandle _numHandle, uint32_t _numIndex = 0, uint32_t _numMax = UINT32_MAX, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)

### Description
Submit primitive for rendering with index and instance data info and draw count from indirect buffers.

### Method
void

### Endpoint
submit

### Parameters
#### Path Parameters
- **_id** (ViewId) - in - View id.
- **_program** (ProgramHandle) - in - Program.
- **_indirectHandle** (IndirectBufferHandle) - in - Indirect buffer.
- **_start** (uint32_t) - in - First element in indirect buffer.
- **_numHandle** (IndexBufferHandle) - in - Buffer for number of draws. Must be created with `BGFX_BUFFER_INDEX32` and `BGFX_BUFFER_DRAW_INDIRECT`.
- **_numIndex** (uint32_t) - in - Element in number buffer.
- **_numMax** (uint32_t) - in - Max number of draws.
- **_depth** (uint32_t) - in - Depth for sorting.
- **_flags** (uint8_t) - in - Discard or preserve states. See `BGFX_DISCARD_*`.
```

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

### Configure Xcode Project for macOS

Source: https://bkaradzic.github.io/bgfx/build.html

Generate an Xcode project for macOS using the GENie tool. This command prepares the workspace for use within the Xcode IDE.

```bash
../bx/tools/bin/darwin/genie --with-combined-examples --xcode=osx xcode9
open .build/projects/xcode9-osx/bgfx.xcworkspace
```

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

### Texture Compiler Usage

Source: https://bkaradzic.github.io/bgfx/tools.html

Basic command-line syntax for converting textures using the texturec tool.

```bash
texturec -f <in> -o <out> [-t <texture format>]
```

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

### Vertex Buffer and Instance Data Functions

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Functions for setting transient vertex buffers, vertex counts, and instance data buffers.

```APIDOC
## void bgfx::setVertexCount(uint32_t _numVertices)

### Description
Set number of vertices for auto generated vertices use in conjunction with gl_VertexID.

### Method
POST

### Endpoint
/bgfx/setVertexCount

### Parameters
#### Query Parameters
- **_numVertices** (uint32_t) - Required - Number of vertices.

### Request Example
```json
{
  "_numVertices": 100
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

### Response Example
```json
{
  "status": "success"
}
```
```

```APIDOC
## void bgfx::setInstanceDataBuffer(const InstanceDataBuffer *_idb)

### Description
Set instance data buffer for draw primitive.

### Method
POST

### Endpoint
/bgfx/setInstanceDataBuffer

### Parameters
#### Request Body
- **_idb** (InstanceDataBuffer) - Required - Transient instance data buffer.

### Request Example
```json
{
  "_idb": {
    "data": "...",
    "size": 1024
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

### Response Example
```json
{
  "status": "success"
}
```
```

```APIDOC
## void bgfx::setInstanceDataBuffer(const InstanceDataBuffer *_idb, uint32_t _start, uint32_t _num)

### Description
Set instance data buffer for draw primitive.

### Method
POST

### Endpoint
/bgfx/setInstanceDataBuffer

### Parameters
#### Query Parameters
- **_start** (uint32_t) - Required - First instance data.
- **_num** (uint32_t) - Required - Number of data instances.

#### Request Body
- **_idb** (InstanceDataBuffer) - Required - Transient instance data buffer.

### Request Example
```json
{
  "_idb": {
    "data": "...",
    "size": 1024
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

### Response Example
```json
{
  "status": "success"
}
```
```

```APIDOC
## void bgfx::setInstanceDataBuffer(VertexBufferHandle _handle, uint32_t _startVertex, uint32_t _num)

### Description
Set instance data buffer for draw primitive.

### Method
POST

### Endpoint
/bgfx/setInstanceDataBuffer

### Parameters
#### Query Parameters
- **_handle** (VertexBufferHandle) - Required - Vertex buffer.
- **_startVertex** (uint32_t) - Required - First instance data.
- **_num** (uint32_t) - Required - Number of data instances.

### Request Example
```json
{
  "_handle": "vb_handle_123",
  "_startVertex": 0,
  "_num": 50
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

### Response Example
```json
{
  "status": "success"
}
```
```

```APIDOC
## void bgfx::setInstanceDataBuffer(DynamicVertexBufferHandle _handle, uint32_t _startVertex, uint32_t _num)

### Description
Set instance data buffer for draw primitive.

### Method
POST

### Endpoint
/bgfx/setInstanceDataBuffer

### Parameters
#### Query Parameters
- **_handle** (DynamicVertexBufferHandle) - Required - Dynamic vertex buffer.
- **_startVertex** (uint32_t) - Required - First instance data.
- **_num** (uint32_t) - Required - Number of data instances.

### Request Example
```json
{
  "_handle": "d vb_handle_456",
  "_startVertex": 0,
  "_num": 50
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

### Response Example
```json
{
  "status": "success"
}
```
```

```APIDOC
## void bgfx::setInstanceCount(uint32_t _numInstances)

### Description
Set number of instances for auto generated instances use in conjunction with gl_InstanceID.

### Method
POST

### Endpoint
/bgfx/setInstanceCount

### Parameters
#### Query Parameters
- **_numInstances** (uint32_t) - Required - Number of instances.

### Request Example
```json
{
  "_numInstances": 10
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

### Response Example
```json
{
  "status": "success"
}
```
```

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

### bgfx::createTexture2D

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Creates a 2D texture with size based on back-buffer ratio.

```APIDOC
## POST bgfx::createTexture2D

### Description
Create texture with size based on back-buffer ratio. Texture will maintain ratio if back buffer resolution changes.

### Parameters
#### Request Body
- **_ratio** (BackbufferRatio::Enum) - Required - Texture size in respect to back-buffer size.
- **_hasMips** (bool) - Required - Indicates that texture contains full mip-map chain.
- **_numLayers** (uint16_t) - Required - Number of layers in texture array. Must be 1 if caps BGFX_CAPS_TEXTURE_2D_ARRAY flag is not set.
- **_format** (TextureFormat::Enum) - Required - Texture format.
- **_flags** (uint64_t) - Optional - Texture creation and sampler flags.

### Response
#### Success Response (200)
- **TextureHandle** (handle) - Texture handle.
```

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

### Buffer Size Configuration

Source: https://bkaradzic.github.io/bgfx/internals.html

Constants defining the initial and maximum sizes for various memory buffers.

```APIDOC
## Buffer Sizes

### Description
These constants define the memory allocation sizes for dynamic buffers, transient buffers, and command buffers.

### Constants
- **BGFX_CONFIG_DYNAMIC_INDEX_BUFFER_SIZE** (int) - Initial size in bytes of dynamic index buffer. Default: 1 MB.
- **BGFX_CONFIG_DYNAMIC_VERTEX_BUFFER_SIZE** (int) - Initial size in bytes of dynamic vertex buffer. Default: 3 MB.
- **BGFX_CONFIG_MAX_TRANSIENT_VERTEX_BUFFER_SIZE** (int) - Maximum transient vertex buffer size. Default: 6 MB.
- **BGFX_CONFIG_MAX_TRANSIENT_INDEX_BUFFER_SIZE** (int) - Maximum transient index buffer size. Default: 2 MB.
- **BGFX_CONFIG_MIN_RESOURCE_COMMAND_BUFFER_SIZE** (int) - Minimum initial size of resource command buffer. Default: 64 KB.
- **BGFX_CONFIG_MIN_UNIFORM_BUFFER_SIZE** (int) - Minimum initial size of per-encoder uniform buffer. Default: 1 MB.
- **BGFX_CONFIG_UNIFORM_BUFFER_RESIZE_THRESHOLD_SIZE** (int) - Max unused uniform buffer space before shrinking. Default: 64 KB.
- **BGFX_CONFIG_UNIFORM_BUFFER_RESIZE_INCREMENT_SIZE** (int) - Increment size for uniform buffer resize. Default: 1 MB.
- **BGFX_CONFIG_CACHED_DEVICE_MEMORY_ALLOCATIONS_SIZE** (int) - Allowed memory allocations for recycling. Default: 128 MB.
- **BGFX_CONFIG_MAX_STAGING_SCRATCH_BUFFER_SIZE** (int) - Threshold for staging scratch buffer usage. Default: 16 MB.
- **BGFX_CONFIG_MAX_SCRATCH_STAGING_BUFFER_PER_FRAME_SIZE** (int) - Reserved scratch buffer size per frame. Default: 32 MB.
```

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

### Shader and Program Management

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Functions for creating, managing, and destroying shaders and shader programs.

```APIDOC
## Shaders and Programs

### Description
APIs for creating, managing, and destroying shaders and shader programs.

### Functions
- `createShader()` - Creates a shader from source code.
- `getShaderUniforms()` - Retrieves uniform information for a shader.
- `destroy()` - Destroys a shader or program.
- `createProgram()` - Creates a shader program from vertex and fragment shaders.
```

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

### bgfx::requestScreenShot

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Requests a screen shot of the window back buffer.

```APIDOC
## FUNCTION bgfx::requestScreenShot

### Description
Request screen shot of window back buffer. Requires bgfx::CallbackI::screenShot to be implemented.

### Parameters
- **_handle** (FrameBufferHandle) - Required - Frame buffer handle.
- **_filePath** (const char*) - Required - File path passed to callback.
```

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

### bgfx::createTextureCube

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Creates a Cube texture.

```APIDOC
## POST bgfx::createTextureCube

### Description
Create Cube texture.

### Parameters
#### Request Body
- **_size** (uint16_t) - Required - Cube side size.
- **_hasMips** (bool) - Required - Indicates that texture contains full mip-map chain.
- **_numLayers** (uint16_t) - Required - Number of layers in texture array.
- **_format** (TextureFormat::Enum) - Required - Texture format.
- **_flags** (uint64_t) - Optional - Texture creation and sampler flags.
- **_mem** (Memory*) - Optional - Texture data.
- **_external** (uint64_t) - Optional - Native API pointer to texture.

### Response
#### Success Response (200)
- **TextureHandle** (handle) - Texture handle.
```

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

### bgfx::touch

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Submits an empty primitive for rendering.

```APIDOC
## FUNCTION bgfx::touch

### Description
Submit an empty primitive for rendering. Uniforms and draw state will be applied but no geometry will be submitted.

### Parameters
- **_id** (ViewId) - Required - View id.
```

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

### Instance and Indirect Buffer Management

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Functions for allocating and managing instance data buffers and indirect buffers.

```APIDOC
## Instance and Indirect Buffer Management

### Description
APIs for managing instance data buffers and indirect buffers used in rendering.

### Instance Buffer
- `getAvailInstanceDataBuffer()` - Gets the available instance data buffer.
- `allocInstanceDataBuffer()` - Allocates an instance data buffer.

### Indirect Buffer
- `createIndirectBuffer()` - Creates an indirect buffer.
- `destroy()` - Destroys an indirect buffer.
```

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

### bgfx::dispatch

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Executes compute shader dispatch commands.

```APIDOC
## void bgfx::dispatch

### Description
Dispatches compute work. Supports both standard dispatch and indirect dispatch.

### Parameters
- **_id** (ViewId) - Required - View id.
- **_program** (ProgramHandle) - Required - Compute program.
- **_numX/Y/Z** (uint32_t) - Optional - Number of groups in X, Y, Z dimensions (standard dispatch).
- **_indirectHandle** (IndirectBufferHandle) - Optional - Indirect buffer (indirect dispatch).
- **_start** (uint32_t) - Optional - First element in indirect buffer.
- **_num** (uint32_t) - Optional - Number of dispatches.
- **_flags** (uint8_t) - Optional - Discard or preserve states.
```

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

### Invoke GENie directly

Source: https://bkaradzic.github.io/bgfx/build.html

Use the GENie executable directly to inspect options or generate project files.

```bash
../bx/tools/bin/<platform>/genie --help
```

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

### bgfx::createTexture3D

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Creates a 3D texture.

```APIDOC
## POST bgfx::createTexture3D

### Description
Create 3D texture.

### Parameters
#### Request Body
- **_width** (uint16_t) - Required - Width.
- **_height** (uint16_t) - Required - Height.
- **_depth** (uint16_t) - Required - Depth.
- **_hasMips** (bool) - Required - Indicates that texture contains full mip-map chain.
- **_format** (TextureFormat::Enum) - Required - Texture format.
- **_flags** (uint64_t) - Optional - Texture creation and sampler flags.
- **_mem** (Memory*) - Optional - Texture data.
- **_external** (uint64_t) - Optional - Native API pointer to texture.

### Response
#### Success Response (200)
- **TextureHandle** (handle) - Texture handle.
```

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

### Uniform Management

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Functions for creating, managing, and querying shader uniforms.

```APIDOC
## Uniform Management

### Description
APIs for creating, managing, and querying shader uniforms.

### Enums
- `bgfx::UniformType` - Enum for uniform data types.
- `bgfx::UniformFreq` - Enum for uniform frequency.

### Structures
- `bgfx::UniformInfo` - Structure for uniform information.

### Functions
- `createUniform()` - Creates a uniform.
- `getUniformInfo()` - Retrieves information about a uniform.
- `destroy()` - Destroys a uniform.
```

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

### Declare API version

Source: https://bkaradzic.github.io/bgfx/idl.html

Sets the API version number within the IDL file.

```lua
version(140)
```

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

### bgfx::getUniformInfo

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Retrieves information about an existing uniform handle.

```APIDOC
## bgfx::getUniformInfo

### Description
Retrieves metadata for a given uniform handle.

### Parameters
- **_handle** (UniformHandle) - Required - Handle to uniform object.
- **_info** (UniformInfo&) - Required - Output structure to store uniform info.
```

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

### Instance Buffer API

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Functions for managing instance data buffers for draw calls.

```APIDOC
## bgfx::getAvailInstanceDataBuffer

### Description
Returns number of requested or maximum available instance buffer slots.

### Parameters
- **_num** (uint32_t) - Required - Number of required instances.
- **_stride** (uint16_t) - Required - Stride per instance.

### Response
- **uint32_t** - Number of requested or maximum available instance buffer slots.

## bgfx::allocInstanceDataBuffer

### Description
Allocate instance data buffer.

### Parameters
- **_idb** (InstanceDataBuffer*) - Required - InstanceDataBuffer structure to be filled.
- **_num** (uint32_t) - Required - Number of instances.
- **_stride** (uint16_t) - Required - Instance stride (must be multiple of 16).
```

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

### dispatch (compute)

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Dispatch compute.

```APIDOC
## void dispatch(ViewId _id, ProgramHandle _program, uint32_t _numX = 1, uint32_t _numY = 1, uint32_t _numZ = 1, uint8_t _flags = BGFX_DISCARD_ALL)

### Description
Dispatch compute.

### Method
void

### Endpoint
dispatch

### Parameters
#### Path Parameters
- **_id** (ViewId) - in - View id.
- **_program** (ProgramHandle) - in - Compute program.
- **_numX** (uint32_t) - in - Number of groups X.
- **_numY** (uint32_t) - in - Number of groups Y.
- **_numZ** (uint32_t) - in - Number of groups Z.
- **_flags** (uint8_t) - in - Discard or preserve states. See `BGFX_DISCARD_*`.
```

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

### bgfx::createTexture2D

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Creates a 2D texture with specified dimensions, format, and optional memory buffer.

```APIDOC
## POST /bgfx::createTexture2D

### Description

Create 2D texture. C99's equivalent binding is `bgfx_create_texture_2d`.

### Method

POST

### Endpoint

/bgfx::createTexture2D

### Parameters

#### Query Parameters

- **_width** (uint16_t) - Required - Width.
- **_height** (uint16_t) - Required - Height.
- **_hasMips** (bool) - Required - Indicates that texture contains full mip-map chain.
- **_numLayers** (uint16_t) - Required - Number of layers in texture array. Must be 1 if caps `BGFX_CAPS_TEXTURE_2D_ARRAY` flag is not set.
- **_format** (TextureFormat::Enum) - Required - Texture format. See: `TextureFormat::Enum`.
- **_flags** (uint64_t) - Optional - Texture creation (see `BGFX_TEXTURE_*`), and sampler (see `BGFX_SAMPLER_*`) flags. Default texture sampling mode is linear, and wrap mode is repeat.
  * `BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP]` - Mirror or clamp to edge wrap mode.
  * `BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]` - Point or anisotropic sampling.
- **_external** (uint64_t) - Optional - External texture handle.

#### Request Body

- **_mem** (Memory) - Optional - DDS, KTX or PVR texture binary data.

### Response

#### Success Response (200)

- **textureHandle** (TextureHandle) - Texture handle.

#### Response Example

```json
{
  "textureHandle": "some_texture_handle_value"
}
```
```

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

### Resource Limits Configuration

Source: https://bkaradzic.github.io/bgfx/internals.html

Constants defining the maximum number of various resources allowed per frame or in total.

```APIDOC
## Resource Limits

### Description
These constants define the maximum capacity for various rendering resources and objects within the bgfx engine.

### Constants
- **BGFX_CONFIG_MAX_DRAW_CALLS** (int) - Maximum number of draw/compute calls per frame. Default: 65535.
- **BGFX_CONFIG_MAX_BLIT_ITEMS** (int) - Maximum number of blit items per frame. Default: 1024.
- **BGFX_CONFIG_MAX_VIEWS** (int) - Maximum number of views. Default: 256 (Must be power of 2).
- **BGFX_CONFIG_MAX_VIEW_NAME** (int) - Maximum length of a view name string. Default: 256.
- **BGFX_CONFIG_MAX_VERTEX_LAYOUTS** (int) - Maximum number of vertex layout declarations. Default: 64.
- **BGFX_CONFIG_MAX_INDEX_BUFFERS** (int) - Maximum number of static index buffer handles. Default: 4096.
- **BGFX_CONFIG_MAX_VERTEX_BUFFERS** (int) - Maximum number of static vertex buffer handles. Default: 4096.
- **BGFX_CONFIG_MAX_VERTEX_STREAMS** (int) - Maximum number of vertex streams per draw call. Default: 4.
- **BGFX_CONFIG_MAX_DYNAMIC_INDEX_BUFFERS** (int) - Maximum number of dynamic index buffer handles. Default: 4096.
- **BGFX_CONFIG_MAX_DYNAMIC_VERTEX_BUFFERS** (int) - Maximum number of dynamic vertex buffer handles. Default: 4096.
- **BGFX_CONFIG_MAX_SHADERS** (int) - Maximum number of shader handles. Default: 512.
- **BGFX_CONFIG_MAX_TEXTURES** (int) - Maximum number of texture handles. Default: 4096.
- **BGFX_CONFIG_MAX_TEXTURE_SAMPLERS** (int) - Maximum number of texture samplers per draw call. Default: 16.
- **BGFX_CONFIG_MAX_FRAME_BUFFERS** (int) - Maximum number of frame buffer handles. Default: 128.
- **BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS** (int) - Maximum number of attachments per frame buffer. Default: 8.
- **BGFX_CONFIG_MAX_UNIFORMS** (int) - Maximum number of uniform handles. Default: 512.
- **BGFX_CONFIG_MAX_OCCLUSION_QUERIES** (int) - Maximum number of occlusion query handles. Default: 256.
- **BGFX_CONFIG_MAX_INSTANCE_DATA_COUNT** (int) - Maximum number of instance data vec4 attributes per draw call. Default: 5.
- **BGFX_CONFIG_MAX_COLOR_PALETTE** (int) - Maximum number of color palette entries. Default: 16.
- **BGFX_CONFIG_MAX_SCREENSHOTS** (int) - Maximum number of screenshot requests per frame. Default: 4.
- **BGFX_CONFIG_MAX_PROGRAMS** (int) - Maximum number of linked programs. Default: 512.
```

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

### Shader Management API

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Functions for creating, querying, and destroying shader objects.

```APIDOC
## bgfx::createShader

### Description
Creates a shader from a memory buffer containing a binary compiled by the shaderc tool.

### Parameters
#### Request Body
- **_mem** (Memory*) - Required - Shader binary data.

### Response
- **ShaderHandle** - The handle to the created shader.

---

## bgfx::getShaderUniforms

### Description
Retrieves the number of non-predefined uniforms and their handles used within a shader.

### Parameters
#### Path Parameters
- **_handle** (ShaderHandle) - Required - The shader handle to query.
- **_uniforms** (UniformHandle*) - Optional - Array to store uniform handles.
- **_max** (uint16_t) - Optional - Maximum capacity of the array.

### Response
- **uint16_t** - Number of uniforms used by the shader.

---

## bgfx::destroy(ShaderHandle)

### Description
Destroys a shader object. It is safe to call this after a program has been created using the shader.

### Parameters
#### Path Parameters
- **_handle** (ShaderHandle) - Required - The shader handle to destroy.
```

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

### Platform Data Structures

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Structures used to hold platform-specific data for window creation and rendering contexts.

```APIDOC
## Platform Specific APIs

These are platform specific APIs. It is only necessary to use these APIs in conjunction with creating windows.

### `struct RenderFrame`

Render frame enum.

**Attention**

C99’s equivalent binding is `bgfx_render_frame_t`.

### `struct InternalData`

Internal data.

**Attention**

C99’s equivalent binding is `bgfx_internal_data_t`.

#### Public Members

- **`const Caps *caps`**: Renderer capabilities.
- **`void *context`**: GL context, or D3D device.

### `struct PlatformData`

Platform data.

**Attention**

C99’s equivalent binding is `bgfx_platform_data_t`.

#### Public Members

- **`void *ndt`**: Native display type (*nix specific).
- **`void *nwh`**: Native window handle. If `NULL`, bgfx will create a headless context/device, provided the rendering API supports it.
- **`void *context`**: GL context, D3D device, or Vulkan device. If `NULL`, bgfx will create context/device.
- **`void *queue`**: D3D12 Queue. If `NULL` bgfx will create queue.
- **`void *backBuffer`**: GL back-buffer, or D3D render target view. If `NULL` bgfx will create back-buffer color surface.
- **`void *backBufferDS`**: Backbuffer depth/stencil. If `NULL`, bgfx will create a back-buffer depth/stencil surface.
- **`NativeWindowHandleType::Enum type`**: Handle type. Needed for platforms having more than one option.
```

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

### Static Index Buffer Management

Source: https://bkaradzic.github.io/bgfx/bgfx.html

Functions for creating, naming, and destroying static index buffers.

```APIDOC
## POST bgfx::createIndexBuffer

### Description
Creates a static index buffer with the provided data and flags.

### Method
POST

### Endpoint
/bgfx/createIndexBuffer

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **_mem** (Memory*) - Required - Pointer to the memory containing the index buffer data.
- **_flags** (uint16_t) - Optional - Buffer creation flags. Defaults to BGFX_BUFFER_NONE.
  - `BGFX_BUFFER_NONE`: No flags.
  - `BGFX_BUFFER_COMPUTE_READ`: Buffer will be read from by compute shader.
  - `BGFX_BUFFER_COMPUTE_WRITE`: Buffer will be written into by compute shader. Cannot be updated from CPU.
  - `BGFX_BUFFER_COMPUTE_READ_WRITE`: Buffer will be used for read/write by compute shader.
  - `BGFX_BUFFER_ALLOW_RESIZE`: Buffer will resize on update if different data size is passed. Only for dynamic buffers.
  - `BGFX_BUFFER_INDEX32`: Buffer uses 32-bit indices. Only for index buffers.

### Request Example
```json
{
  "_mem": {"data": "...", "size": 1234},
  "_flags": 0
}
```

### Response
#### Success Response (200)
- **IndexBufferHandle** - Handle to the created static index buffer.

#### Response Example
```json
{
  "handle": "0x12345678"
}
```

## POST bgfx::setName

### Description
Sets a debug name for a static index buffer.

### Method
POST

### Endpoint
/bgfx/setName

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **_handle** (IndexBufferHandle) - Required - Handle to the static index buffer.
- **_name** (const char*) - Required - The name to assign to the index buffer.
- **_len** (int32_t) - Optional - The length of the name. Defaults to INT32_MAX (zero-terminated string expected).

### Request Example
```json
{
  "_handle": "0x12345678",
  "_name": "MyIndexBuffer",
  "_len": -1
}
```

### Response
#### Success Response (200)
None

#### Response Example
None

## POST bgfx::destroy

### Description
Destroys a static index buffer.

### Method
POST

### Endpoint
/bgfx/destroy

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **_handle** (IndexBufferHandle) - Required - Handle to the static index buffer to destroy.

### Request Example
```json
{
  "_handle": "0x12345678"
}
```

### Response
#### Success Response (200)
None

#### Response Example
None
```