# API Reference

Note

If you’re just getting started with bgfx, you might get more out of these simple walkthroughs for how to use bgfx’s API:

- Hello, bgfx! (tutorial)

- bgfx-minimal-example (repo on GitHub)

- Using the bgfx library with C++ on Ubuntu (tutorial)

- Getting started with BGFX (playlist on Youtube)

- Getting started with BGFX (repo on GitHub)

## General

### Initialization and Shutdown

struct Init

  Initialization parameters used by `bgfx::init`.

  Attention

    C99’s equivalent binding is `bgfx_init_t`.

  Public Members

  RendererType :: Enum type

    Select rendering backend. When set to RendererType::Count a default rendering backend will be selected appropriate to the platform. See: `bgfx::RendererType`

  uint16_t vendorId

    Vendor PCI ID. If set to `BGFX_PCI_ID_NONE`, discrete and integrated GPUs will be prioritised.

    - `BGFX_PCI_ID_NONE` - Auto-select 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.

  uint16_t deviceId

    Device ID. If set to 0 it will select first device, or device with matching ID.

  uint64_t capabilities

    Capabilities initialization mask (default: UINT64_MAX).

  bool debug

    Enable device for debugging.

  bool profile

    Enable device for profiling.

  bool fallback

    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.

  CallbackI *callback

    Provide application specific callback interface. See: `bgfx::CallbackI`

  bx::AllocatorI *allocator

    Custom allocator. When a custom allocator is not specified, bgfx uses the CRT allocator. Bgfx assumes custom allocator is thread safe.

  struct Limits

    Configurable runtime limits parameters.

    Attention

      C99’s equivalent binding is `bgfx_init_limits_t`.

    Public Members

    uint16_t maxEncoders

      Maximum number of encoder threads.

    uint32_t minResourceCbSize

      Minimum resource command buffer size.

    uint32_t maxTransientVbSize

      Maximum transient vertex buffer size.

    uint32_t maxTransientIbSize

      Maximum transient index buffer size.

    uint32_t minUniformBufferSize

      Mimimum uniform buffer size.

struct Resolution

  Backbuffer resolution and reset parameters.

  Attention

    C99’s equivalent binding is `bgfx_resolution_t`.

  Public Members

  TextureFormat :: Enum formatColor

    Backbuffer color format.

  TextureFormat :: Enum formatDepthStencil

    Backbuffer depth/stencil format.

  uint32_t width

    Backbuffer width.

  uint32_t height

    Backbuffer height.

  uint32_t reset

    Reset parameters.

  uint8_t numBackBuffers

    Number of back buffers.

  uint8_t maxFrameLatency

    Maximum frame latency.

  uint8_t debugTextScale

    Scale factor for debug text.

bool bgfx::init(const Init &_init = {})

  Initialize the bgfx library.

  Attention

    C99’s equivalent binding is `bgfx_init`.

  Parameters:

    _init – [in] Initialization parameters. See: `bgfx::Init` for more info.

  Returns:

    `true` if initialization was successful.

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.

struct CallbackI

  Callback interface to implement application specific behavior. Cached items are currently used for OpenGL and Direct3D 12 binary shaders.

  Remark

  ’fatal’ and ‘trace’ callbacks can be called from any thread. Other callbacks are called from the render thread.

  Attention

    C99’s equivalent binding is `bgfx_callback_interface_t`.

  Public Functions

  virtual void fatal(const char *_filePath, uint16_t _line, Fatal::Enum _code, const char *_str) = 0

    This callback is called on unrecoverable errors. It’s not safe to continue (Excluding _code `Fatal::DebugCheck`), inform the user and terminate the application.

    Remark

    Not thread safe and it can be called from any thread.

    Attention

      C99’s equivalent binding is `bgfx_callback_vtbl.fatal`.

    Parameters:

      - _filePath – [in] File path where fatal message was generated.

      - _line – [in] Line where fatal message was generated.

      - _code – [in] Fatal error code.

      - _str – [in] More information about error.

  virtual void traceVargs(const char *_filePath, uint16_t _line, const char *_format, va_list _argList) = 0

    Print debug message.

    Remark

    Not thread safe and it can be called from any thread.

    Attention

      C99’s equivalent binding is `bgfx_callback_vtbl.trace_vargs`.

    Parameters:

      - _filePath – [in] File path where debug message was generated.

      - _line – [in] Line where debug message was generated.

      - _format – [in] `printf` style format.

      - _argList – [in] Variable arguments list initialized with `va_start`.

  virtual void profilerBegin(const char *_name, uint32_t _abgr, const char *_filePath, uint16_t _line) = 0

    Profiler region begin.

    Remark

    Not thread safe and it can be called from any thread.

    Attention

      C99’s equivalent binding is `bgfx_callback_vtbl.profiler_begin`.

    Parameters:

      - _name – [in] Region name, contains dynamic string.

      - _abgr – [in] Color of profiler region.

      - _filePath – [in] File path where `profilerBegin` was called.

      - _line – [in] Line where `profilerBegin` was called.

  virtual void profilerBeginLiteral(const char *_name, uint32_t _abgr, const char *_filePath, uint16_t _line) = 0

    Profiler region begin with string literal name.

    Remark

    Not thread safe and it can be called from any thread.

    Attention

      C99’s equivalent binding is `bgfx_callback_vtbl.profiler_begin_literal`.

    Parameters:

      - _name – [in] Region name, contains string literal.

      - _abgr – [in] Color of profiler region.

      - _filePath – [in] File path where `profilerBeginLiteral` was called.

      - _line – [in] Line where `profilerBeginLiteral` was called.

  virtual void profilerEnd() = 0

    Profiler region end.

    Remark

    Not thread safe and it can be called from any thread.

    Attention

      C99’s equivalent binding is `bgfx_callback_vtbl.profiler_end`.

  virtual uint32_t cacheReadSize(uint64_t _id) = 0

    Returns the size of a cached item. Returns 0 if no cached item was found.

    Attention

      C99’s equivalent binding is `bgfx_callback_vtbl.cache_read_size`.

    Parameters:

      _id – [in] Cache id.

    Returns:

      Number of bytes to read.

  virtual bool cacheRead(uint64_t _id, void *_data, uint32_t _size) = 0

    Read cached item.

    Attention

      C99’s equivalent binding is `bgfx_callback_vtbl.cache_read`.

    Parameters:

      - _id – [in] Cache id.

      - _data – [in] Buffer where to read data.

      - _size – [in] Size of data to read.

    Returns:

      True if data is read.

  virtual void cacheWrite(uint64_t _id, const void *_data, uint32_t _size) = 0

    Write cached item.

    Attention

      C99’s equivalent binding is `bgfx_callback_vtbl.cache_write`.

    Parameters:

      - _id – [in] Cache id.

      - _data – [in] Data to write.

      - _size – [in] Size of data to write.

  virtual void screenShot(const char *_filePath, uint32_t _width, uint32_t _height, uint32_t _pitch, const void *_data, uint32_t _size, bool _yflip) = 0

    Screenshot captured. Screenshot format is always 4-byte BGRA.

    Attention

      C99’s equivalent binding is `bgfx_callback_vtbl.screen_shot`.

    Parameters:

      - _filePath – [in] File path.

      - _width – [in] Image width.

      - _height – [in] Image height.

      - _pitch – [in] Number of bytes to skip between the start of each horizontal line of the image.

      - _data – [in] Image data.

      - _size – [in] Image size.

      - _yflip – [in] If true, image origin is bottom left.

  virtual void captureBegin(uint32_t _width, uint32_t _height, uint32_t _pitch, TextureFormat :: Enum _format, bool _yflip) = 0

    Called when a video capture begins.

    Attention

      C99’s equivalent binding is `bgfx_callback_vtbl.capture_begin`.

    Parameters:

      - _width – [in] Image width.

      - _height – [in] Image height.

      - _pitch – [in] Number of bytes to skip between the start of each horizontal line of the image.

      - _format – [in] Texture format. See: `TextureFormat::Enum`.

      - _yflip – [in] If true, image origin is bottom left.

  virtual void captureEnd() = 0

    Called when a video capture ends.

    Attention

      C99’s equivalent binding is `bgfx_callback_vtbl.capture_end`.

  virtual void captureFrame(const void *_data, uint32_t _size) = 0

    Captured frame.

    Attention

      C99’s equivalent binding is `bgfx_callback_vtbl.capture_frame`.

    Parameters:

      - _data – [in] Image data.

      - _size – [in] Image size.

void bgfx::shutdown()

  Shutdown bgfx library.

  Attention

    C99’s equivalent binding is `bgfx_shutdown`.

### Updating

#### Reset

void bgfx::reset(uint32_t _width, uint32_t _height, uint32_t _flags = BGFX_RESET_NONE, TextureFormat :: Enum _format = TextureFormat :: Count )

  Reset graphic settings and back-buffer size.

  Attention

    This call doesn’t change the window size, it just resizes the back-buffer. Your windowing code controls the window size.

  Attention

    C99’s equivalent binding is `bgfx_reset`.

  Parameters:

    - _width – [in] Back-buffer width.

    - _height – [in] Back-buffer height.

    - _flags – [in] See: `BGFX_RESET_*` for more info.

      - `BGFX_RESET_NONE` - No reset flags.

      - `BGFX_RESET_FULLSCREEN` - Not supported yet.

      - `BGFX_RESET_MSAA_X[2/4/8/16]` - Enable 2, 4, 8 or 16 x MSAA.

      - `BGFX_RESET_VSYNC` - Enable V-Sync.

      - `BGFX_RESET_MAXANISOTROPY` - Turn on/off max anisotropy.

      - `BGFX_RESET_CAPTURE` - Begin screen capture.

      - `BGFX_RESET_FLUSH_AFTER_RENDER` - Flush rendering after submitting to GPU.

      - `BGFX_RESET_FLIP_AFTER_RENDER` - This flag specifies where flip occurs. Default behavior is that flip occurs before rendering new frame. This flag only has effect when `BGFX_CONFIG_MULTITHREADED=0`.

      - `BGFX_RESET_SRGB_BACKBUFFER` - Enable sRGB back-buffer.

    - _format – [in] Texture format. See: `TextureFormat::Enum`.

BGFX_RESET_NONE

  No reset flags.

BGFX_RESET_MSAA_X2

  Enable 2x MSAA.

BGFX_RESET_MSAA_X4

  Enable 4x MSAA.

BGFX_RESET_MSAA_X8

  Enable 8x MSAA.

BGFX_RESET_MSAA_X16

  Enable 16x MSAA.

BGFX_RESET_FULLSCREEN

  Not supported yet.

BGFX_RESET_VSYNC

  Enable V-Sync.

BGFX_RESET_MAXANISOTROPY

  Turn on/off max anisotropy.

BGFX_RESET_CAPTURE

  Begin screen capture.

BGFX_RESET_FLUSH_AFTER_RENDER

  Flush rendering after submitting to GPU.

BGFX_RESET_FLIP_AFTER_RENDER

  This flag specifies where flip occurs. Default behaviour is that flip occurs before rendering new frame. This flag only has effect when `BGFX_CONFIG_MULTITHREADED=0`.

BGFX_RESET_SRGB_BACKBUFFER

  Enable sRGB backbuffer.

BGFX_RESET_HDR10

  Enable HDR10 rendering.

BGFX_RESET_HIDPI

  Enable HiDPI rendering.

BGFX_RESET_DEPTH_CLAMP

  Enable depth clamp.

BGFX_RESET_SUSPEND

  Suspend rendering.

BGFX_RESET_TRANSPARENT_BACKBUFFER

  Transparent backbuffer. Availability depends on: `BGFX_CAPS_TRANSPARENT_BACKBUFFER`.

#### Frame

uint32_t bgfx::frame(bool _capture = false)

  Advance to next frame. When using multithreaded renderer, this call just swaps internal buffers, kicks render thread, and returns. In singlethreaded renderer this call does frame rendering.

  Attention

    C99’s equivalent binding is `bgfx_frame`.

  Parameters:

    _capture – [in] Capture frame with graphics debugger.

  Returns:

    Current frame number. This might be used in conjunction with double/multi buffering data outside the library and passing it to library via `bgfx::makeRef` calls.

### Debug

#### Debug Features

void bgfx::setDebug(uint32_t _debug)

  Set debug flags.

  Attention

    C99’s equivalent binding is `bgfx_set_debug`.

  Parameters:

    _debug – [in] Available flags:

    - `BGFX_DEBUG_IFH` - Infinitely fast hardware. When this flag is set all rendering calls will be skipped. This is useful when profiling to quickly assess potential bottlenecks between CPU and GPU.

    - `BGFX_DEBUG_PROFILER` - Enable profiler.

    - `BGFX_DEBUG_STATS` - Display internal statistics.

    - `BGFX_DEBUG_TEXT` - Display debug text.

    - `BGFX_DEBUG_WIREFRAME` - Wireframe rendering. All rendering primitives will be rendered as lines.

#### Debug Flags

BGFX_DEBUG_NONE

  No debug.

BGFX_DEBUG_WIREFRAME

  Enable wireframe for all primitives.

BGFX_DEBUG_IFH

  Enable infinitely fast hardware test. No draw calls will be submitted to driver. It’s useful when profiling to quickly assess bottleneck between CPU and GPU.

BGFX_DEBUG_STATS

  Enable statistics display.

BGFX_DEBUG_TEXT

  Enable debug text display.

BGFX_DEBUG_PROFILER

  Enable profiler. This causes per-view statistics to be collected, available through `bgfx::Stats::ViewStats`. This is unrelated to the profiler functions in `bgfx::CallbackI`.

#### Debug Text Display

void bgfx::dbgTextClear(uint8_t _attr = 0, bool _small = false)

  Clear internal debug text buffer.

  Attention

    C99’s equivalent binding is `bgfx_dbg_text_clear`.

  Parameters:

    - _attr – [in] Background color.

    - _small – [in] Default 8x16 or 8x8 font.

void bgfx::dbgTextPrintf(uint16_t _x, uint16_t _y, uint8_t _attr, const char *_format, ...)

  Print into internal debug text character-buffer (VGA-compatible text mode).

  Attention

    C99’s equivalent binding is `bgfx_dbg_text_printf`.

  Parameters:

    - _x – [in] The X coordinate (2D position from top-left)

    - _y – [in] The Y coordinate (2D position from top-left)

    - _attr – [in] Color palette. Where top 4-bits represent index of background, and bottom 4-bits represent foreground color from standard VGA text palette (ANSI escape codes).

    - _format – [in] `printf` style format.

void bgfx::dbgTextPrintfVargs(uint16_t _x, uint16_t _y, uint8_t _attr, const char *_format, va_list _argList)

  Print into internal debug text character-buffer (VGA-compatible text mode).

  Attention

    C99’s equivalent binding is `bgfx_dbg_text_vprintf`.

  Parameters:

    - _x – [in] The X coordinate (2D position from top-left)

    - _y – [in] The Y coordinate (2D position from top-left)

    - _attr – [in] Color palette. Where top 4-bits represent index of background, and bottom 4-bits represent foreground color from standard VGA text palette (ANSI escape codes).

    - _format – [in] `printf` style format.

    - _argList – [in] additional arguments for format string

void bgfx::dbgTextImage(uint16_t _x, uint16_t _y, uint16_t _width, uint16_t _height, const void *_data, uint16_t _pitch)

  Draw image into internal debug text buffer.

  Attention

    C99’s equivalent binding is `bgfx_dbg_text_image`.

  Parameters:

    - _x – [in] The X coordinate (2D position from top-left)

    - _y – [in] The Y coordinate (2D position from top-left)

    - _width – [in] Image width

    - _height – [in] Image height

    - _data – [in] Raw image data (character/attribute raw encoding).

    - _pitch – [in] Image pitch in bytes.

### Querying information

#### Renderer

uint8_t bgfx::getSupportedRenderers(uint8_t _max = 0, RendererType :: Enum *_enum = NULL)

  Returns supported backend API renderers.

  Attention

    C99’s equivalent binding is `bgfx_get_supported_renderers`.

  Parameters:

    - _max – [in] Maximum number of elements in _enum array.

    - _enum – [inout] Array where supported renderers will be written.

  Returns:

    Number of supported renderers.

RendererType :: Enum bgfx::getRendererType()

  Returns current renderer backend API type.

  Remark

  Library must be initialized.

  Attention

    C99’s equivalent binding is `bgfx_get_renderer_type`.

struct RendererType

  Renderer backend type enum.

  Attention

    C99’s equivalent binding is `bgfx_renderer_type_t`.

  Public Types

  enum Enum

    Renderer types:

    Values:

    enumerator Noop

      No rendering.

    enumerator Agc

      AGC.

    enumerator Direct3D11

      Direct3D 11.0.

    enumerator Direct3D12

      Direct3D 12.0.

    enumerator Gnm

      GNM.

    enumerator Metal

      Metal.

    enumerator Nvn

      NVN.

    enumerator OpenGLES

      OpenGL ES 2.0+.

    enumerator OpenGL

      OpenGL 2.1+.

    enumerator Vulkan

      Vulkan.

    enumerator WebGPU

      WebGPU.

    enumerator Count

#### Capabilities

const Caps *bgfx::getCaps()

  Returns renderer capabilities.

  Remark

  Library must be initialized.

  Attention

    C99’s equivalent binding is `bgfx_get_caps`.

  Returns:

    Pointer to static `bgfx::Caps` structure.

struct Caps

  Renderer capabilities.

  Attention

    C99’s equivalent binding is `bgfx_caps_t`.

  Public Members

  RendererType :: Enum rendererType

    Renderer backend type. See: `bgfx::RendererType`

  uint64_t supported

    Supported functionality.

    Attention

      See `BGFX_CAPS_*` flags at https://bkaradzic.github.io/bgfx/bgfx.html#available-caps

  uint16_t vendorId

    Selected GPU vendor PCI id.

  uint16_t deviceId

    Selected GPU device id.

  bool homogeneousDepth

    True when NDC depth is in [-1, 1] range, otherwise its [0, 1].

  bool originBottomLeft

    True when NDC origin is at bottom left.

  uint8_t numGPUs

    Number of enumerated GPUs.

  GPU gpu[4]

    Enumerated GPUs.

  Limits limits

    Renderer runtime limits.

  uint16_t formats[ TextureFormat :: Count ]

    Supported texture format capabilities flags:

    - `BGFX_CAPS_FORMAT_TEXTURE_NONE` - Texture format is not supported.

    - `BGFX_CAPS_FORMAT_TEXTURE_2D` - Texture format is supported.

    - `BGFX_CAPS_FORMAT_TEXTURE_2D_SRGB` - Texture as sRGB format is supported.

    - `BGFX_CAPS_FORMAT_TEXTURE_2D_EMULATED` - Texture format is emulated.

    - `BGFX_CAPS_FORMAT_TEXTURE_3D` - Texture format is supported.

    - `BGFX_CAPS_FORMAT_TEXTURE_3D_SRGB` - Texture as sRGB format is supported.

    - `BGFX_CAPS_FORMAT_TEXTURE_3D_EMULATED` - Texture format is emulated.

    - `BGFX_CAPS_FORMAT_TEXTURE_CUBE` - Texture format is supported.

    - `BGFX_CAPS_FORMAT_TEXTURE_CUBE_SRGB` - Texture as sRGB format is supported.

    - `BGFX_CAPS_FORMAT_TEXTURE_CUBE_EMULATED` - Texture format is emulated.

    - `BGFX_CAPS_FORMAT_TEXTURE_VERTEX` - Texture format can be used from vertex shader.

    - `BGFX_CAPS_FORMAT_TEXTURE_IMAGE_READ` - Texture format can be used as image and read from.

    - `BGFX_CAPS_FORMAT_TEXTURE_IMAGE_WRITE` - Texture format can be used as image and written to.

    - `BGFX_CAPS_FORMAT_TEXTURE_FRAMEBUFFER` - Texture format can be used as frame buffer.

    - `BGFX_CAPS_FORMAT_TEXTURE_FRAMEBUFFER_MSAA` - Texture format can be used as MSAA frame buffer.

    - `BGFX_CAPS_FORMAT_TEXTURE_MSAA` - Texture can be sampled as MSAA.

    - `BGFX_CAPS_FORMAT_TEXTURE_MIP_AUTOGEN` - Texture format supports auto-generated mips.

  struct GPU

    GPU info.

    Attention

      C99’s equivalent binding is `bgfx_caps_gpu_t`.

    Public Members

    uint16_t vendorId

      Vendor PCI id. See `BGFX_PCI_ID_*`.

    uint16_t deviceId

      Device id.

  struct Limits

    Renderer runtime limits.

    Attention

      C99’s equivalent binding is `bgfx_caps_limits_t`.

    Public Members

    uint32_t maxDrawCalls

      Maximum number of draw calls.

    uint32_t maxBlits

      Maximum number of blit calls.

    uint32_t maxTextureSize

      Maximum texture size.

    uint32_t maxTextureLayers

      Maximum texture layers.

    uint32_t maxViews

      Maximum number of views.

    uint32_t maxFrameBuffers

      Maximum number of frame buffer handles.

    uint32_t maxFBAttachments

      Maximum number of frame buffer attachments.

    uint32_t maxPrograms

      Maximum number of program handles.

    uint32_t maxShaders

      Maximum number of shader handles.

    uint32_t maxTextures

      Maximum number of texture handles.

    uint32_t maxTextureSamplers

      Maximum number of texture samplers.

    uint32_t maxComputeBindings

      Maximum number of compute bindings.

    uint32_t maxVertexLayouts

      Maximum number of vertex format layouts.

    uint32_t maxVertexStreams

      Maximum number of vertex streams.

    uint32_t maxIndexBuffers

      Maximum number of index buffer handles.

    uint32_t maxVertexBuffers

      Maximum number of vertex buffer handles.

    uint32_t maxDynamicIndexBuffers

      Maximum number of dynamic index buffer handles.

    uint32_t maxDynamicVertexBuffers

      Maximum number of dynamic vertex buffer handles.

    uint32_t maxUniforms

      Maximum number of uniform handles.

    uint32_t maxOcclusionQueries

      Maximum number of occlusion query handles.

    uint32_t maxEncoders

      Maximum number of encoder threads.

    uint32_t minResourceCbSize

      Minimum resource command buffer size.

    uint32_t maxTransientVbSize

      Maximum transient vertex buffer size.

    uint32_t maxTransientIbSize

      Maximum transient index buffer size.

    uint32_t minUniformBufferSize

      Mimimum uniform buffer size.

##### Available Caps

BGFX_CAPS_ALPHA_TO_COVERAGE

  Alpha to coverage is supported.

BGFX_CAPS_BLEND_INDEPENDENT

  Blend independent is supported.

BGFX_CAPS_COMPUTE

  Compute shaders are supported.

BGFX_CAPS_CONSERVATIVE_RASTER

  Conservative rasterization is supported.

BGFX_CAPS_DRAW_INDIRECT

  Draw indirect is supported.

BGFX_CAPS_DRAW_INDIRECT_COUNT

  Draw indirect with indirect count is supported.

BGFX_CAPS_FRAGMENT_DEPTH

  Fragment depth is available in fragment shader.

BGFX_CAPS_FRAGMENT_ORDERING

  Fragment ordering is available in fragment shader.

BGFX_CAPS_GRAPHICS_DEBUGGER

  Graphics debugger is present.

BGFX_CAPS_HDR10

  HDR10 rendering is supported.

BGFX_CAPS_HIDPI

  HiDPI rendering is supported.

BGFX_CAPS_IMAGE_RW

  Image Read/Write is supported.

BGFX_CAPS_INDEX32

  32-bit indices are supported.

BGFX_CAPS_INSTANCING

  Instancing is supported.

BGFX_CAPS_OCCLUSION_QUERY

  Occlusion query is supported.

BGFX_CAPS_PRIMITIVE_ID

  PrimitiveID is available in fragment shader.

BGFX_CAPS_RENDERER_MULTITHREADED

  Renderer is on separate thread.

BGFX_CAPS_SWAP_CHAIN

  Multiple windows are supported.

BGFX_CAPS_TEXTURE_BLIT

  Texture blit is supported.

BGFX_CAPS_TEXTURE_COMPARE_LEQUAL

  Texture compare less equal mode is supported.

BGFX_CAPS_TEXTURE_CUBE_ARRAY

  Cubemap texture array is supported.

BGFX_CAPS_TEXTURE_DIRECT_ACCESS

  CPU direct access to GPU texture memory.

BGFX_CAPS_TEXTURE_READ_BACK

  Read-back texture is supported.

BGFX_CAPS_TEXTURE_2D_ARRAY

  2D texture array is supported.

BGFX_CAPS_TEXTURE_3D

  3D textures are supported.

BGFX_CAPS_TRANSPARENT_BACKBUFFER

  Transparent back buffer supported.

BGFX_CAPS_VARIABLE_RATE_SHADING

  Variable Rate Shading.

BGFX_CAPS_VERTEX_ATTRIB_HALF

  Vertex attribute half-float is supported.

BGFX_CAPS_VERTEX_ATTRIB_UINT10

  Vertex attribute 10_10_10_2 is supported.

BGFX_CAPS_VERTEX_ID

  Rendering with VertexID only is supported.

BGFX_CAPS_VIEWPORT_LAYER_ARRAY

  Viewport layer is available in vertex shader. All texture compare modes are supported.

#### Statistics

const Stats *bgfx::getStats()

  Returns performance counters.

  Attention

    Pointer returned is valid until `bgfx::frame` is called.

  Attention

    C99’s equivalent binding is `bgfx_get_stats`.

struct Stats

  Renderer statistics data.

  Remark

  All time values are high-resolution timestamps, while time frequencies define timestamps-per-second for that hardware.

  Attention

    C99’s equivalent binding is `bgfx_stats_t`.

  Public Members

  int64_t cpuTimeFrame

    CPU time between two `bgfx::frame` calls.

  int64_t cpuTimeBegin

    Render thread CPU submit begin time.

  int64_t cpuTimeEnd

    Render thread CPU submit end time.

  int64_t cpuTimerFreq

    CPU timer frequency. Timestamps-per-second.

  int64_t gpuTimeBegin

    GPU frame begin time.

  int64_t gpuTimeEnd

    GPU frame end time.

  int64_t gpuTimerFreq

    GPU timer frequency.

  int64_t waitRender

    Time spent waiting for render backend thread to finish issuing draw commands to underlying graphics API.

  int64_t waitSubmit

    Time spent waiting for submit thread to advance to next frame.

  uint32_t numDraw

    Number of draw calls submitted.

  uint32_t numCompute

    Number of compute calls submitted.

  uint32_t numBlit

    Number of blit calls submitted.

  uint32_t maxGpuLatency

    GPU driver latency.

  uint32_t gpuFrameNum

    Frame which generated gpuTimeBegin, gpuTimeEnd.

  uint16_t numDynamicIndexBuffers

    Number of used dynamic index buffers.

  uint16_t numDynamicVertexBuffers

    Number of used dynamic vertex buffers.

  uint16_t numFrameBuffers

    Number of used frame buffers.

  uint16_t numIndexBuffers

    Number of used index buffers.

  uint16_t numOcclusionQueries

    Number of used occlusion queries.

  uint16_t numPrograms

    Number of used programs.

  uint16_t numShaders

    Number of used shaders.

  uint16_t numTextures

    Number of used textures.

  uint16_t numUniforms

    Number of used uniforms.

  uint16_t numVertexBuffers

    Number of used vertex buffers.

  uint16_t numVertexLayouts

    Number of used vertex layouts.

  int64_t textureMemoryUsed

    Estimate of texture memory used.

  int64_t rtMemoryUsed

    Estimate of render target memory used.

  int32_t transientVbUsed

    Amount of transient vertex buffer used.

  int32_t transientIbUsed

    Amount of transient index buffer used.

  uint32_t numPrims[Topology::Count]

    Number of primitives rendered.

  int64_t gpuMemoryMax

    Maximum available GPU memory for application.

  int64_t gpuMemoryUsed

    Amount of GPU memory used by the application.

  uint16_t width

    Backbuffer width in pixels.

  uint16_t height

    Backbuffer height in pixels.

  uint16_t textWidth

    Debug text width in characters.

  uint16_t textHeight

    Debug text height in characters.

  uint16_t numViews

    Number of view stats.

  ViewStats *viewStats

    Array of View stats.

  uint8_t numEncoders

    Number of encoders used during frame.

  EncoderStats *encoderStats

    Array of encoder stats.

struct ViewStats

  View stats.

  Attention

    C99’s equivalent binding is `bgfx_view_stats_t`.

  Public Members

  char name[256]

    View name.

  ViewId view

    View id.

  int64_t cpuTimeBegin

    CPU (submit) begin time.

  int64_t cpuTimeEnd

    CPU (submit) end time.

  int64_t gpuTimeBegin

    GPU begin time.

  int64_t gpuTimeEnd

    GPU end time.

  uint32_t gpuFrameNum

    Frame which generated gpuTimeBegin, gpuTimeEnd.

struct EncoderStats

  Encoder stats.

  Attention

    C99’s equivalent binding is `bgfx_encoder_stats_t`.

  Public Members

  int64_t cpuTimeBegin

    Encoder thread CPU submit begin time.

  int64_t cpuTimeEnd

    Encoder thread CPU submit end time.

### Platform specific

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

RenderFrame ::Enum bgfx::renderFrame(int32_t _msecs = -1)

  Render frame.

  Attention

    `bgfx::renderFrame` is blocking call. It waits for `bgfx::frame` to be called from API thread to process frame. If timeout value is passed call will timeout and return even if `bgfx::frame` is not called.

  Attention

    C99’s equivalent binding is `bgfx_render_frame`.

  Warning

  This call should be only used on platforms that don’t allow creating separate rendering thread. If it is called before to bgfx::init, render thread won’t be created by bgfx::init call.

  Parameters:

    _msecs – Timeout in milliseconds.

  Returns:

    Current renderer state. See: `bgfx::RenderFrame`.

struct RenderFrame

  Render frame enum.

  Attention

    C99’s equivalent binding is `bgfx_render_frame_t`.

void bgfx::setPlatformData(const PlatformData &_data)

  Set platform data.

  Attention

    C99’s equivalent binding is `bgfx_set_platform_data`.

  Warning

  Must be called before `bgfx::init`.

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

const InternalData *bgfx::getInternalData()

  Get internal data for interop.

  Attention

    It’s expected you understand some bgfx internals before you use this call.

  Attention

    C99’s equivalent binding is `bgfx_get_internal_data`.

  Warning

  Must be called only on render thread.

struct InternalData

  Internal data.

  Attention

    C99’s equivalent binding is `bgfx_internal_data_t`.

  Public Members

  const struct Caps *caps

    Renderer capabilities.

  void *context

    GL context, or D3D device.

uintptr_t bgfx::overrideInternal(TextureHandle _handle, uintptr_t _ptr, uint16_t _layerIndex = 0)

  Override internal texture with externally created texture. Previously created internal texture will released.

  Attention

    It’s expected you understand some bgfx internals before you use this call.

  Attention

    C99’s equivalent binding is `bgfx_override_internal_texture_ptr`.

  Warning

  Must be called only on render thread.

  Parameters:

    - _handle – [in] Texture handle.

    - _ptr – [in] Native API pointer to texture.

    - _layerIndex – [in] Layer index for texture arrays (only implemented for D3D11).

  Returns:

    Native API pointer to texture. If result is 0, texture is not created yet from the main thread.

uintptr_t bgfx::overrideInternal(TextureHandle _handle, uint16_t _width, uint16_t _height, uint8_t _numMips, TextureFormat :: Enum _format, uint64_t _flags = BGFX_TEXTURE_NONE | BGFX_SAMPLER_NONE)

  Override internal texture by creating new texture. Previously created internal texture will released.

  Attention

    It’s expected you understand some bgfx internals before you use this call.

  Attention

    C99’s equivalent binding is `bgfx_override_internal_texture`.

  Warning

  Must be called only on render thread.

  Parameters:

    - _handle – [in] Texture handle.

    - _width – [in] Width.

    - _height – [in] Height.

    - _numMips – [in] Number of mip-maps.

    - _format – [in] Texture format. See: `TextureFormat::Enum`.

    - _flags – [in] 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.

  Returns:

    Native API pointer to texture. If result is 0, texture is not created yet from the main thread.

### Miscellaneous

void bgfx::vertexPack(const float _input[4], bool _inputNormalized, Attrib :: Enum _attr, const VertexLayout &_layout, void *_data, uint32_t _index = 0)

  Pack vertex attribute into vertex stream format.

  Attention

    C99’s equivalent binding is `bgfx_vertex_pack`.

  Parameters:

    - _input – [in] Value to be packed into vertex stream.

    - _inputNormalized – [in] True if input value is already normalized.

    - _attr – [in] Attribute to pack.

    - _layout – [in] Vertex stream layout.

    - _data – [in] Destination vertex stream where data will be packed.

    - _index – [in] Vertex index that will be modified.

void bgfx::vertexUnpack(float _output[4], Attrib :: Enum _attr, const VertexLayout &_layout, const void *_data, uint32_t _index = 0)

  Unpack vertex attribute from vertex stream format.

  Attention

    C99’s equivalent binding is `bgfx_vertex_unpack`.

  Parameters:

    - _output – [out] Result of unpacking.

    - _attr – [in] Attribute to unpack.

    - _layout – [in] Vertex stream layout.

    - _data – [in] Source vertex stream from where data will be unpacked.

    - _index – [in] Vertex index that will be unpacked.

void bgfx::vertexConvert(const VertexLayout &_destLayout, void *_destData, const VertexLayout &_srcLayout, const void *_srcData, uint32_t _num = 1)

  Converts vertex stream data from one vertex stream format to another.

  Attention

    C99’s equivalent binding is `bgfx_vertex_convert`.

  Parameters:

    - _destLayout – [in] Destination vertex stream layout.

    - _destData – [in] Destination vertex stream.

    - _srcLayout – [in] Source vertex stream layout.

    - _srcData – [in] Source vertex stream data.

    - _num – [in] Number of vertices to convert from source to destination.

uint32_t bgfx::weldVertices(void *_output, const VertexLayout &_layout, const void *_data, uint32_t _num, bool _index32, float _epsilon = 0.001f)

  Weld vertices.

  Attention

    C99’s equivalent binding is `bgfx_weld_vertices`.

  Parameters:

    - _output – [in] Welded vertices remapping table. The size of buffer must be the same as number of vertices.

    - _layout – [in] Vertex stream layout.

    - _data – [in] Vertex stream.

    - _num – [in] Number of vertices in vertex stream.

    - _index32 – [in] Set to `true` if input indices are 32-bit.

    - _epsilon – [in] Error tolerance for vertex position comparison.

  Returns:

    Number of unique vertices after vertex welding.

struct TopologyConvert

  Topology conversion function.

  Attention

    C99’s equivalent binding is `bgfx_topology_convert_t`.

  Public Types

  enum Enum

    Topology conversion functions:

    Values:

    enumerator TriListFlipWinding

      Flip winding order of triangle list.

    enumerator TriStripFlipWinding

      Flip winding order of triangle strip.

    enumerator TriListToLineList

      Convert triangle list to line list.

    enumerator TriStripToTriList

      Convert triangle strip to triangle list.

    enumerator LineStripToLineList

      Convert line strip to line list.

    enumerator Count

uint32_t bgfx::topologyConvert( TopologyConvert :: Enum _conversion, void *_dst, uint32_t _dstSize, const void *_indices, uint32_t _numIndices, bool _index32)

  Convert index buffer for use with different primitive topologies.

  Attention

    C99’s equivalent binding is `bgfx_topology_convert`.

  Parameters:

    - _conversion – [in] Conversion type, see `TopologyConvert::Enum`.

    - _dst – [in] Destination index buffer. If this argument is NULL function will return number of indices after conversion.

    - _dstSize – [in] Destination index buffer in bytes. It must be large enough to contain output indices. If destination size is insufficient index buffer will be truncated.

    - _indices – [in] Source indices.

    - _numIndices – [in] Number of input indices.

    - _index32 – [in] Set to `true` if input indices are 32-bit.

  Returns:

    Number of output indices after conversion.

struct TopologySort

  Topology sort order.

  Attention

    C99’s equivalent binding is `bgfx_topology_sort_t`.

  Public Types

  enum Enum

    Topology sort order:

    Values:

    enumerator DirectionFrontToBackMin
    enumerator DirectionFrontToBackAvg
    enumerator DirectionFrontToBackMax
    enumerator DirectionBackToFrontMin
    enumerator DirectionBackToFrontAvg
    enumerator DirectionBackToFrontMax
    enumerator DistanceFrontToBackMin
    enumerator DistanceFrontToBackAvg
    enumerator DistanceFrontToBackMax
    enumerator DistanceBackToFrontMin
    enumerator DistanceBackToFrontAvg
    enumerator DistanceBackToFrontMax
    enumerator Count

void bgfx::topologySortTriList( TopologySort :: Enum _sort, void *_dst, uint32_t _dstSize, const float _dir[3], const float _pos[3], const void *_vertices, uint32_t _stride, const void *_indices, uint32_t _numIndices, bool _index32)

  Sort indices.

  Attention

    C99’s equivalent binding is `bgfx_topology_sort_tri_list`.

  Parameters:

    - _sort – [in] Sort order, see `TopologySort::Enum`.

    - _dst – [in] Destination index buffer.

    - _dstSize – [in] Destination index buffer in bytes. It must be large enough to contain output indices. If destination size is insufficient index buffer will be truncated.

    - _dir – [in] Direction (vector must be normalized).

    - _pos – [in] Position.

    - _vertices – [in] Pointer to first vertex represented as float x, y, z. Must contain at least number of vertices referencende by index buffer.

    - _stride – [in] Vertex stride.

    - _indices – [in] Source indices.

    - _numIndices – [in] Number of input indices.

    - _index32 – [in] Set to `true` if input indices are 32-bit.

void bgfx::discard(uint8_t _flags = BGFX_DISCARD_ALL)

  Discard all previously set state for draw or compute call.

  Attention

    C99’s equivalent binding is `bgfx_discard`.

  Parameters:

    _flags – [in] Draw/compute states to discard.

void bgfx::touch(ViewId _id)

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

  These empty draw calls will sort before ordinary draw calls.

  Attention

    C99’s equivalent binding is `bgfx_touch`.

  Parameters:

    _id – [in] View id.

void bgfx::setPaletteColor(uint8_t _index, uint32_t _rgba)

  Set palette color value.

  Attention

    C99’s equivalent binding is `bgfx_set_palette_color`.

  Parameters:

    - _index – [in] Index into palette.

    - _rgba – [in] Packed 32-bit RGBA value.

void bgfx::setPaletteColor(uint8_t _index, const float _rgba[4])

  Set palette color value.

  Attention

    C99’s equivalent binding is `bgfx_set_palette_color`.

  Parameters:

    - _index – [in] Index into palette.

    - _rgba – [in] RGBA floating point value.

void bgfx::setPaletteColor(uint8_t _index, float _r, float _g, float _b, float _a)

  Set palette color value.

  Attention

    C99’s equivalent binding is `bgfx_set_palette_color`.

  Parameters:

    - _index – [in] Index into palette.

    - _r – [in] Red value (RGBA floating point values)

    - _g – [in] Green value (RGBA floating point values)

    - _b – [in] Blue value (RGBA floating point values)

    - _a – [in] Alpha value (RGBA floating point values)

void bgfx::requestScreenShot(FrameBufferHandle _handle, const char *_filePath)

  Request screen shot of window back buffer.

  Remark

  `bgfx::CallbackI::screenShot` must be implemented.

  Attention

    Frame buffer handle must be created with OS’ target native window handle.

  Attention

    C99’s equivalent binding is `bgfx_request_screen_shot`.

  Parameters:

    - _handle – [in] Frame buffer handle. If handle is `BGFX_INVALID_HANDLE` request will be made for main window back buffer.

    - _filePath – [in] Will be passed to `bgfx::CallbackI::screenShot` callback.

## Views

Views are the primary sorting mechanism in bgfx. They represent buckets of draw and compute calls, or what are often known as ‘passes’.

When compute calls and draw calls occupy the same bucket, the compute calls will be sorted to execute first. Compute calls are always executed in order of submission, while draw calls are sorted by internal state if the View is not in sequential mode. In most cases where the z-buffer is used, this change in order does not affect the desired output. When draw call order needs to be preserved (e.g. when rendering GUIs), Views can be set to use sequential mode with bgfx::setViewMode. Sequential order is less efficient, because it doesn’t allow state change optimization, and should be avoided when possible.

By default, Views are sorted by their View ID, in ascending order. For dynamic renderers where the right order might not be known until the last moment, View IDs can be changed to use arbitrary ordering with bgfx::setViewOrder.

A View’s state is preserved between frames.

void bgfx::setViewName(ViewId _id, const char *_name, int32_t _len = INT32_MAX)

  Set view name.

  In graphics debugger view name will appear as:

      "nnnce <view name>"
       ^  ^^ ^
       |  |+-- eye (L/R)
       |  +--- compute (C)
       +------ view id

  Remark

  This is debug only feature.

  Attention

    C99’s equivalent binding is `bgfx_set_view_name`.

  Parameters:

    - _id – [in] View id.

    - _name – [in] View name.

    - _len – [in] View name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.

void bgfx::setViewRect(ViewId _id, uint16_t _x, uint16_t _y, uint16_t _width, uint16_t _height)

  Set view rectangle. Draw primitive outside view will be clipped.

  Attention

    C99’s equivalent binding is `bgfx_set_view_rect`.

  Parameters:

    - _id – [in] View id.

    - _x – [in] Position x from the left corner of the window.

    - _y – [in] Position y from the top corner of the window.

    - _width – [in] Width of view port region.

    - _height – [in] Height of view port region.

void bgfx::setViewRect(ViewId _id, uint16_t _x, uint16_t _y, BackbufferRatio::Enum _ratio)

  Set view rectangle. Draw primitive outside view will be clipped.

  Attention

    C99’s equivalent binding is `bgfx_set_view_rect_ratio`.

  Parameters:

    - _id – [in] View id.

    - _x – [in] Position x from the left corner of the window.

    - _y – [in] Position y from the top corner of the window.

    - _ratio – [in] Width and height will be set in respect to back-buffer size. See: `BackbufferRatio::Enum`.

void bgfx::setViewScissor(ViewId _id, uint16_t _x = 0, uint16_t _y = 0, uint16_t _width = 0, uint16_t _height = 0)

  Set view scissor. Draw primitive outside view will be clipped. When _x, _y, _width and _height are set to 0, scissor will be disabled.

  Attention

    C99’s equivalent binding is `bgfx_set_view_scissor`.

  Parameters:

    - _id – [in] View id.

    - _x – [in] Position x from the left corner of the window.

    - _y – [in] Position y from the top corner of the window.

    - _width – [in] Width of scissor region.

    - _height – [in] Height of scissor region.

void bgfx::setViewClear(ViewId _id, uint16_t _flags, uint32_t _rgba = 0x000000ff, float _depth = 1.0f, uint8_t _stencil = 0)

  Set view clear flags.

  Attention

    C99’s equivalent binding is `bgfx_set_view_clear`.

  Parameters:

    - _id – [in] View id.

    - _flags – [in] Clear flags. Use `BGFX_CLEAR_NONE` to remove any clear operation. See: `BGFX_CLEAR_*`.

    - _rgba – [in] Color clear value.

    - _depth – [in] Depth clear value.

    - _stencil – [in] Stencil clear value.

void bgfx::setViewClear(ViewId _id, uint16_t _flags, float _depth, uint8_t _stencil, uint8_t _0 = UINT8_MAX, uint8_t _1 = UINT8_MAX, uint8_t _2 = UINT8_MAX, uint8_t _3 = UINT8_MAX, uint8_t _4 = UINT8_MAX, uint8_t _5 = UINT8_MAX, uint8_t _6 = UINT8_MAX, uint8_t _7 = UINT8_MAX)

  Set view clear flags with different clear color for each frame buffer texture. `bgfx::setPaletteColor` must be used to set up a clear color palette.

  Attention

    C99’s equivalent binding is `bgfx_set_view_clear_mrt`.

  Parameters:

    - _id – [in] View id.

    - _flags – [in] Clear flags. Use `BGFX_CLEAR_NONE` to remove any clear operation. See: `BGFX_CLEAR_*`.

    - _depth – [in] Depth clear value.

    - _stencil – [in] Stencil clear value.

    - _0 – [in] Palette index for frame buffer attachment 0.

    - _1 – [in] Palette index for frame buffer attachment 1.

    - _2 – [in] Palette index for frame buffer attachment 2.

    - _3 – [in] Palette index for frame buffer attachment 3.

    - _4 – [in] Palette index for frame buffer attachment 4.

    - _5 – [in] Palette index for frame buffer attachment 5.

    - _6 – [in] Palette index for frame buffer attachment 6.

    - _7 – [in] Palette index for frame buffer attachment 7.

struct ViewMode

  View mode sets draw call sort order.

  Attention

    C99’s equivalent binding is `bgfx_view_mode_t`.

  Public Types

  enum Enum

    View modes:

    Values:

    enumerator Default

      Default sort order.

    enumerator Sequential

      Sort in the same order in which submit calls were called.

    enumerator DepthAscending

      Sort draw call depth in ascending order.

    enumerator DepthDescending

      Sort draw call depth in descending order.

    enumerator Count

void bgfx::setViewMode(ViewId _id, ViewMode :: Enum _mode = ViewMode :: Default )

  Set view sorting mode.

  Remark

  View mode must be set prior calling `bgfx::submit` for the view.

  Attention

    C99’s equivalent binding is `bgfx_set_view_mode`.

  Parameters:

    - _id – [in] View id.

    - _mode – [in] View sort mode. See `ViewMode::Enum`.

void bgfx::setViewFrameBuffer(ViewId _id, FrameBufferHandle _handle)

  Set view frame buffer.

  Remark

  Not persistent after `bgfx::reset` call.

  Attention

    C99’s equivalent binding is `bgfx_set_view_frame_buffer`.

  Parameters:

    - _id – [in] View id.

    - _handle – [in] Frame buffer handle. Passing `BGFX_INVALID_HANDLE` as frame buffer handle will draw primitives from this view into default back buffer.

void bgfx::setViewTransform(ViewId _id, const void *_view, const void *_proj)

  Set view’s view matrix and projection matrix, all draw primitives in this view will use these two matrices.

  Attention

    C99’s equivalent binding is `bgfx_set_view_transform`.

  Parameters:

    - _id – [in] View id.

    - _view – [in] View matrix.

    - _proj – [in] Projection matrix.

void bgfx::setViewOrder(ViewId _id = 0, uint16_t _num = UINT16_MAX, const ViewId *_remap = NULL)

  Post submit view reordering.

  Attention

    C99’s equivalent binding is `bgfx_set_view_order`.

  Parameters:

    - _id – [in] First view id.

    - _num – [in] Number of views to remap.

    - _remap – [in] View remap id table. Passing `NULL` will reset view ids to default state.

struct ShadingRate

  Shading Rate.

  Attention

    C99’s equivalent binding is `bgfx_bgfx_shading_rate_t`.

  Public Types

  enum Enum

    Shading rate:

    Values:

    enumerator Rate1x1
    enumerator Rate1x2
    enumerator Rate2x1
    enumerator Rate2x2
    enumerator Rate2x4
    enumerator Rate4x2
    enumerator Rate4x4
    enumerator Count

void bgfx::setViewShadingRate(ViewId _id, ShadingRate :: Enum _shadingRate = ShadingRate :: Rate1x1 )

  Set view shading rate.

  Attention

    Availability depends on: `BGFX_CAPS_VARIABLE_RATE_SHADING`.

  Attention

    C99’s equivalent binding is `bgfx_set_view_shading_rate`.

  Parameters:

    - _id – [in] View id.

    - _shadingRate – [in] Shading rate.

void bgfx::resetView(ViewId _id)

  Reset all view settings to default.

  Attention

    C99’s equivalent binding is `bgfx_reset_view`.

  Parameters:

    _id – [in] View id.

## Encoder

API for multi-threaded submission.

Encoder *bgfx::begin(bool _forThread = false)

  Begin submitting draw calls from thread.

  Parameters:

    _forThread – [in] Explicitly request an encoder for a worker thread.

void bgfx::end( Encoder *_encoder)

  End submitting draw calls from thread.

struct Encoder

  Encoders are used for submitting draw calls from multiple threads. Only one encoder per thread should be used. Use `bgfx::begin()` to obtain an encoder for a thread.

  Attention

    C99’s equivalent binding is `bgfx_encoder`.

  Public Functions

  void setMarker(const char *_name, int32_t _len = INT32_MAX)

    Sets a debug marker. This allows you to group graphics calls together for easy browsing in graphics debugging tools.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_marker`.

    Parameters:

      - _name – [in] Marker name.

      - _len – [in] Marker name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.

  void setState(uint64_t _state, uint32_t _rgba = 0)

    Set render states for draw primitive.

    Remark

    1. To set up more complex states use: `BGFX_STATE_ALPHA_REF(_ref)`, `BGFX_STATE_POINT_SIZE(_size)`, `BGFX_STATE_BLEND_FUNC(_src, _dst)`, `BGFX_STATE_BLEND_FUNC_SEPARATE(_srcRGB, _dstRGB, _srcA, _dstA)`, `BGFX_STATE_BLEND_EQUATION(_equation)`, `BGFX_STATE_BLEND_EQUATION_SEPARATE(_equationRGB, _equationA)`

    2. `BGFX_STATE_BLEND_EQUATION_ADD` is set when no other blend equation is specified.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_state`.

    Parameters:

      - _state – [in] State flags. Default state for primitive type is triangles. See: `BGFX_STATE_DEFAULT`.

        - `BGFX_STATE_DEPTH_TEST_*` - Depth test function.

        - `BGFX_STATE_BLEND_*` - See remark 1 about BGFX_STATE_BLEND_FUNC.

        - `BGFX_STATE_BLEND_EQUATION_*` - See remark 2.

        - `BGFX_STATE_CULL_*` - Backface culling mode.

        - `BGFX_STATE_WRITE_*` - Enable R, G, B, A or Z write.

        - `BGFX_STATE_MSAA` - Enable hardware multisample antialiasing.

        - `BGFX_STATE_PT_[TRISTRIP/LINES/POINTS]` - Primitive type.

      - _rgba – [in] Sets blend factor used by `BGFX_STATE_BLEND_FACTOR` and `BGFX_STATE_BLEND_INV_FACTOR` blend modes.

  void setCondition(OcclusionQueryHandle _handle, bool _visible)

    Set condition for rendering.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_condition`.

    Parameters:

      - _handle – [in] Occlusion query handle.

      - _visible – [in] Render if occlusion query is visible.

  void setStencil(uint32_t _fstencil, uint32_t _bstencil = BGFX_STENCIL_NONE)

    Set stencil test state.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_stencil`.

    Parameters:

      - _fstencil – [in] Front stencil state.

      - _bstencil – [in] Back stencil state. If back is set to `BGFX_STENCIL_NONE` _fstencil is applied to both front and back facing primitives.

  uint16_t setScissor(uint16_t _x, uint16_t _y, uint16_t _width, uint16_t _height)

    Set scissor for draw primitive. To scissor for all primitives in view see `bgfx::setViewScissor`.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_scissor`.

    Parameters:

      - _x – [in] Position x from the left side of the window.

      - _y – [in] Position y from the top of the window.

      - _width – [in] Width of scissor region.

      - _height – [in] Height of scissor region.

    Returns:

      Scissor cache index.

  void setScissor(uint16_t _cache = UINT16_MAX)

    Set scissor from cache for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_scissor_cached`.

    Parameters:

      _cache – [in] Index in scissor cache. Pass UINT16_MAX to have primitive use view scissor instead.

  uint32_t setTransform(const void *_mtx, uint16_t _num = 1)

    Set model matrix for draw primitive. If it is not called, model will be rendered with identity model matrix.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_transform`.

    Parameters:

      - _mtx – [in] Pointer to first matrix in array.

      - _num – [in] Number of matrices in array.

    Returns:

      Index into matrix cache in case the same model matrix has to be used for other draw primitive call.

  uint32_t allocTransform(Transform *_transform, uint16_t _num)

    Reserve `_num` matrices in internal matrix cache.

    Attention

      Pointer returned can be modified until `bgfx::frame` is called.

    Attention

      C99’s equivalent binding is `bgfx_encoder_alloc_transform`.

    Parameters:

      - _transform – [in] Pointer to `Transform` structure.

      - _num – [in] Number of matrices.

    Returns:

      Index into matrix cache.

  void setTransform(uint32_t _cache, uint16_t _num = 1)

    Set model matrix from matrix cache for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_transform_cached`.

    Parameters:

      - _cache – [in] Index in matrix cache.

      - _num – [in] Number of matrices from cache.

  void setUniform(UniformHandle _handle, const void *_value, uint16_t _num = 1)

    Set shader uniform parameter for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_uniform`.

    Parameters:

      - _handle – [in] Uniform.

      - _value – [in] Pointer to uniform data.

      - _num – [in] Number of elements. Passing `UINT16_MAX` will use the _num passed on uniform creation.

  void setIndexBuffer(IndexBufferHandle _handle)

    Set index buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_index_buffer`.

    Parameters:

      _handle – [in] Index buffer.

  void setIndexBuffer(IndexBufferHandle _handle, uint32_t _firstIndex, uint32_t _numIndices)

    Set index buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_index_buffer`.

    Parameters:

      - _handle – [in] Index buffer.

      - _firstIndex – [in] First index to render.

      - _numIndices – [in] Number of indices to render.

  void setIndexBuffer(DynamicIndexBufferHandle _handle)

    Set index buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_dynamic_index_buffer`.

    Parameters:

      _handle – [in] Dynamic index buffer.

  void setIndexBuffer(DynamicIndexBufferHandle _handle, uint32_t _firstIndex, uint32_t _numIndices)

    Set index buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_dynamic_index_buffer`.

    Parameters:

      - _handle – [in] Dynamic index buffer.

      - _firstIndex – [in] First index to render.

      - _numIndices – [in] Number of indices to render.

  void setIndexBuffer(const TransientIndexBuffer *_tib)

    Set index buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_transient_index_buffer`.

    Parameters:

      _tib – [in] Transient index buffer.

  void setIndexBuffer(const TransientIndexBuffer *_tib, uint32_t _firstIndex, uint32_t _numIndices)

    Set index buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_transient_index_buffer`.

    Parameters:

      - _tib – [in] Transient index buffer.

      - _firstIndex – [in] First index to render.

      - _numIndices – [in] Number of indices to render.

  void setVertexBuffer(uint8_t _stream, VertexBufferHandle _handle)

    Set vertex buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_vertex_buffer`.

    Parameters:

      - _stream – [in] Vertex stream.

      - _handle – [in] Vertex buffer.

  void setVertexBuffer(uint8_t _stream, VertexBufferHandle _handle, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)

    Set vertex buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_vertex_buffer`.

    Parameters:

      - _stream – [in] Vertex stream.

      - _handle – [in] Vertex buffer.

      - _startVertex – [in] First vertex to render.

      - _numVertices – [in] Number of vertices to render.

      - _layoutHandle – [in] Vertex layout for aliasing vertex buffer. If invalid handle is used, vertex layout used for creation of vertex buffer will be used.

  void setVertexBuffer(uint8_t _stream, DynamicVertexBufferHandle _handle)

    Set vertex buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_dynamic_vertex_buffer`.

    Parameters:

      - _stream – [in] Vertex stream.

      - _handle – [in] Dynamic vertex buffer.

  void setVertexBuffer(uint8_t _stream, DynamicVertexBufferHandle _handle, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)

    Set vertex buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_dynamic_vertex_buffer`.

    Parameters:

      - _stream – [in] Vertex stream.

      - _handle – [in] Dynamic vertex buffer.

      - _startVertex – [in] First vertex to render.

      - _numVertices – [in] Number of vertices to render.

      - _layoutHandle – [in] Vertex layout for aliasing vertex buffer. If invalid handle is used, vertex layout used for creation of vertex buffer will be used.

  void setVertexBuffer(uint8_t _stream, const TransientVertexBuffer *_tvb)

    Set vertex buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_transient_vertex_buffer`.

    Parameters:

      - _stream – [in] Vertex stream.

      - _tvb – [in] Transient vertex buffer.

  void setVertexBuffer(uint8_t _stream, const TransientVertexBuffer *_tvb, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)

    Set vertex buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_transient_vertex_buffer`.

    Parameters:

      - _stream – [in] Vertex stream.

      - _tvb – [in] Transient vertex buffer.

      - _startVertex – [in] First vertex to render.

      - _numVertices – [in] Number of vertices to render.

      - _layoutHandle – [in] Vertex layout for aliasing vertex buffer. If invalid handle is used, vertex layout used for creation of vertex buffer will be used.

  void setVertexCount(uint32_t _numVertices)

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

    Attention

      Availability depends on: `BGFX_CAPS_VERTEX_ID`.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_vertex_count`.

    Parameters:

      _numVertices – [in] Number of vertices.

  void setInstanceDataBuffer(const InstanceDataBuffer *_idb)

    Set instance data buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_instance_data_buffer`.

    Parameters:

      _idb – [in] Transient instance data buffer.

  void setInstanceDataBuffer(const InstanceDataBuffer *_idb, uint32_t _start, uint32_t _num)

    Set instance data buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_instance_data_buffer`.

    Parameters:

      - _idb – [in] Transient instance data buffer.

      - _start – [in] First instance data.

      - _num – [in] Number of data instances.

  void setInstanceDataBuffer(VertexBufferHandle _handle, uint32_t _start, uint32_t _num)

    Set instance data buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_instance_data_from_vertex_buffer`.

    Parameters:

      - _handle – [in] Vertex buffer.

      - _start – [in] First instance data.

      - _num – [in] Number of data instances.

  void setInstanceDataBuffer(DynamicVertexBufferHandle _handle, uint32_t _start, uint32_t _num)

    Set instance data buffer for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_instance_data_from_dynamic_vertex_buffer`.

    Parameters:

      - _handle – [in] Vertex buffer.

      - _start – [in] First instance data.

      - _num – [in] Number of data instances.

  void setInstanceCount(uint32_t _numInstances)

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

    Attention

      Availability depends on: `BGFX_CAPS_VERTEX_ID`.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_instance_count`.

    Parameters:

      _numInstances – [in] Number of instances.

  void setTexture(uint8_t _stage, UniformHandle _sampler, TextureHandle _handle, uint32_t _flags = UINT32_MAX)

    Set texture stage for draw primitive.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_texture`.

    Parameters:

      - _stage – [in] Texture unit.

      - _sampler – [in] Program sampler.

      - _handle – [in] Texture handle.

      - _flags – [in] Texture sampling mode. Default value UINT32_MAX uses texture sampling settings from the texture.

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

  void touch(ViewId _id)

    Submit an empty primitive for rendering. Uniforms and draw state will be applied but no geometry will be submitted. Useful in cases when no other draw/compute primitive is submitted to view, but it’s desired to execute clear view.

    These empty draw calls will sort before ordinary draw calls.

    Attention

      C99’s equivalent binding is `bgfx_encoder_touch`.

    Parameters:

      _id – [in] View id.

  void submit(ViewId _id, ProgramHandle _program, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)

    Submit primitive for rendering.

    Attention

      C99’s equivalent binding is `bgfx_encoder_submit`.

    Parameters:

      - _id – [in] View id.

      - _program – [in] Program.

      - _depth – [in] Depth for sorting.

      - _flags – [in] Discard or preserve states. See `BGFX_DISCARD_*`.

  void submit(ViewId _id, ProgramHandle _program, OcclusionQueryHandle _occlusionQuery, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)

    Submit primitive with occlusion query for rendering.

    Attention

      C99’s equivalent binding is `bgfx_encoder_submit_occlusion_query`.

    Parameters:

      - _id – [in] View id.

      - _program – [in] Program.

      - _occlusionQuery – [in] Occlusion query.

      - _depth – [in] Depth for sorting.

      - _flags – [in] Discard or preserve states. See `BGFX_DISCARD_*`.

  void submit(ViewId _id, ProgramHandle _program, IndirectBufferHandle _indirectHandle, uint32_t _start = 0, uint32_t _num = 1, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)

    Submit primitive for rendering with index and instance data info from indirect buffer.

    Attention

      Availability depends on: `BGFX_CAPS_DRAW_INDIRECT`.

    Attention

      C99’s equivalent binding is `bgfx_encoder_submit_indirect`.

    Parameters:

      - _id – [in] View id.

      - _program – [in] Program.

      - _indirectHandle – [in] Indirect buffer.

      - _start – [in] First element in indirect buffer.

      - _num – [in] Number of draws.

      - _depth – [in] Depth for sorting.

      - _flags – [in] Discard or preserve states. See `BGFX_DISCARD_*`.

  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)

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

    Attention

      Availability depends on: `BGFX_CAPS_DRAW_INDIRECT_COUNT`.

    Attention

      C99’s equivalent binding is `bgfx_encoder_submit_indirect_count`.

    Parameters:

      - _id – [in] View id.

      - _program – [in] Program.

      - _indirectHandle – [in] Indirect buffer.

      - _start – [in] First element in indirect buffer.

      - _numHandle – [in] Buffer for number of draws. Must be created with `BGFX_BUFFER_INDEX32` and `BGFX_BUFFER_DRAW_INDIRECT`.

      - _numIndex – [in] Element in number buffer.

      - _numMax – [in] Max number of draws.

      - _depth – [in] Depth for sorting.

      - _flags – [in] Discard or preserve states. See `BGFX_DISCARD_*`.

  void setBuffer(uint8_t _stage, IndexBufferHandle _handle, Access :: Enum _access)

    Set compute index buffer.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_compute_index_buffer`.

    Parameters:

      - _stage – [in] Compute stage.

      - _handle – [in] Index buffer handle.

      - _access – [in] Buffer access. See `Access::Enum`.

  void setBuffer(uint8_t _stage, VertexBufferHandle _handle, Access :: Enum _access)

    Set compute vertex buffer.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_compute_vertex_buffer`.

    Parameters:

      - _stage – [in] Compute stage.

      - _handle – [in] Vertex buffer handle.

      - _access – [in] Buffer access. See `Access::Enum`.

  void setBuffer(uint8_t _stage, DynamicIndexBufferHandle _handle, Access :: Enum _access)

    Set compute dynamic index buffer.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_compute_dynamic_index_buffer`.

    Parameters:

      - _stage – [in] Compute stage.

      - _handle – [in] Dynamic index buffer handle.

      - _access – [in] Buffer access. See `Access::Enum`.

  void setBuffer(uint8_t _stage, DynamicVertexBufferHandle _handle, Access :: Enum _access)

    Set compute dynamic vertex buffer.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_compute_dynamic_vertex_buffer`.

    Parameters:

      - _stage – [in] Compute stage.

      - _handle – [in] Dynamic vertex buffer handle.

      - _access – [in] Buffer access. See `Access::Enum`.

  void setBuffer(uint8_t _stage, IndirectBufferHandle _handle, Access :: Enum _access)

    Set compute indirect buffer.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_compute_indirect_buffer`.

    Parameters:

      - _stage – [in] Compute stage.

      - _handle – [in] Indirect buffer handle.

      - _access – [in] Buffer access. See `Access::Enum`.

  void setImage(uint8_t _stage, TextureHandle _handle, uint8_t _mip, Access :: Enum _access, TextureFormat :: Enum _format = TextureFormat :: Count )

    Set compute image from texture.

    Attention

      C99’s equivalent binding is `bgfx_encoder_set_image`.

    Parameters:

      - _stage – [in] Texture unit.

      - _handle – [in] Texture handle.

      - _mip – [in] Mip level.

      - _access – [in] Texture access. See `Access::Enum`.

      - _format – [in] Texture format. See: `TextureFormat::Enum`.

  void dispatch(ViewId _id, ProgramHandle _handle, uint32_t _numX = 1, uint32_t _numY = 1, uint32_t _numZ = 1, uint8_t _flags = BGFX_DISCARD_ALL)

    Dispatch compute.

    Attention

      C99’s equivalent binding is `bgfx_encoder_dispatch`.

    Parameters:

      - _id – [in] View id.

      - _handle – [in] Compute program.

      - _numX – [in] Number of groups X.

      - _numY – [in] Number of groups Y.

      - _numZ – [in] Number of groups Z.

      - _flags – [in] Discard or preserve states. See `BGFX_DISCARD_*`.

  void dispatch(ViewId _id, ProgramHandle _handle, IndirectBufferHandle _indirectHandle, uint32_t _start = 0, uint32_t _num = 1, uint8_t _flags = BGFX_DISCARD_ALL)

    Dispatch compute indirect.

    Attention

      C99’s equivalent binding is `bgfx_encoder_dispatch_indirect`.

    Parameters:

      - _id – [in] View id.

      - _handle – [in] Compute program.

      - _indirectHandle – [in] Indirect buffer.

      - _start – [in] First element in indirect buffer.

      - _num – [in] Number of dispatches.

      - _flags – [in] Discard or preserve states. See `BGFX_DISCARD_*`.

  void discard(uint8_t _flags = BGFX_DISCARD_ALL)

    Discard all previously set state for draw or compute call.

    Attention

      C99’s equivalent binding is `bgfx_encoder_discard`.

    Parameters:

      _flags – [in] Draw/compute states to discard.

  void blit(ViewId _id, TextureHandle _dst, uint16_t _dstX, uint16_t _dstY, TextureHandle _src, uint16_t _srcX = 0, uint16_t _srcY = 0, uint16_t _width = UINT16_MAX, uint16_t _height = UINT16_MAX)

    Blit texture 2D region between two 2D textures.

    Attention

      Destination texture must be created with `BGFX_TEXTURE_BLIT_DST` flag.

    Attention

      Availability depends on: `BGFX_CAPS_TEXTURE_BLIT`.

    Attention

      C99’s equivalent binding is `bgfx_encoder_blit`.

    Parameters:

      - _id – [in] View id.

      - _dst – [in] Destination texture handle.

      - _dstX – [in] Destination texture X position.

      - _dstY – [in] Destination texture Y position.

      - _src – [in] Source texture handle.

      - _srcX – [in] Source texture X position.

      - _srcY – [in] Source texture Y position.

      - _width – [in] Width of region.

      - _height – [in] Height of region.

  void blit(ViewId _id, TextureHandle _dst, uint8_t _dstMip, uint16_t _dstX, uint16_t _dstY, uint16_t _dstZ, TextureHandle _src, uint8_t _srcMip = 0, uint16_t _srcX = 0, uint16_t _srcY = 0, uint16_t _srcZ = 0, uint16_t _width = UINT16_MAX, uint16_t _height = UINT16_MAX, uint16_t _depth = UINT16_MAX)

    Blit texture region between two textures.

    Attention

      Destination texture must be created with `BGFX_TEXTURE_BLIT_DST` flag.

    Attention

      Availability depends on: `BGFX_CAPS_TEXTURE_BLIT`.

    Attention

      C99’s equivalent binding is `bgfx_encoder_blit`.

    Parameters:

      - _id – [in] View id.

      - _dst – [in] Destination texture handle.

      - _dstMip – [in] Destination texture mip level.

      - _dstX – [in] Destination texture X position.

      - _dstY – [in] Destination texture Y position.

      - _dstZ – [in] If texture is 2D this argument should be 0. If destination texture is cube this argument represents destination texture cube face. For 3D texture this argument represents destination texture Z position.

      - _src – [in] Source texture handle.

      - _srcMip – [in] Source texture mip level.

      - _srcX – [in] Source texture X position.

      - _srcY – [in] Source texture Y position.

      - _srcZ – [in] If texture is 2D this argument should be 0. If source texture is cube this argument represents source texture cube face. For 3D texture this argument represents source texture Z position.

      - _width – [in] Width of region.

      - _height – [in] Height of region.

      - _depth – [in] If texture is 3D this argument represents depth of region, otherwise it’s unused.

### Draw

Draw state is not preserved between two draw calls. All state is cleared after calling bgfx::submit.

#### State

#### Debug

void bgfx::setMarker(const char *_name, int32_t _len = INT32_MAX)

  Sets a debug marker. This allows you to group graphics calls together for easy browsing in graphics debugging tools.

  Attention

    C99’s equivalent binding is `bgfx_set_marker`.

  Parameters:

    - _name – [in] Marker name.

    - _len – [in] Marker name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.

void bgfx::setName(ShaderHandle _handle, const char *_name, int32_t _len = INT32_MAX)

  Set shader debug name.

  Attention

    C99’s equivalent binding is `bgfx_set_shader_name`.

  Parameters:

    - _handle – [in] Shader handle.

    - _name – [in] Shader name.

    - _len – [in] Shader name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.

void bgfx::setName(TextureHandle _handle, const char *_name, int32_t _len = INT32_MAX)

  Set texture debug name.

  Attention

    C99’s equivalent binding is `bgfx_set_texture_name`.

  Parameters:

    - _handle – [in] Texture handle.

    - _name – [in] Texture name.

    - _len – [in] Texture name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.

#### State

void bgfx::setState(uint64_t _state, uint32_t _rgba = 0)

  Set render states for draw primitive.

  Remark

  1. To set up more complex states use: `BGFX_STATE_ALPHA_REF(_ref)`, `BGFX_STATE_POINT_SIZE(_size)`, `BGFX_STATE_BLEND_FUNC(_src, _dst)`, `BGFX_STATE_BLEND_FUNC_SEPARATE(_srcRGB, _dstRGB, _srcA, _dstA)` `BGFX_STATE_BLEND_EQUATION(_equation)` `BGFX_STATE_BLEND_EQUATION_SEPARATE(_equationRGB, _equationA)`

  2. `BGFX_STATE_BLEND_EQUATION_ADD` is set when no other blend equation is specified.

  Attention

    C99’s equivalent binding is `bgfx_set_state`.

  Parameters:

    - _state – [in] State flags. Default state for primitive type is triangles. See: `BGFX_STATE_DEFAULT`.

      - `BGFX_STATE_DEPTH_TEST_*` - Depth test function.

      - `BGFX_STATE_BLEND_*` - See remark 1 about BGFX_STATE_BLEND_FUNC.

      - `BGFX_STATE_BLEND_EQUATION_*` - See remark 2.

      - `BGFX_STATE_CULL_*` - Backface culling mode.

      - `BGFX_STATE_WRITE_*` - Enable R, G, B, A or Z write.

      - `BGFX_STATE_MSAA` - Enable MSAA.

      - `BGFX_STATE_PT_[TRISTRIP/LINES/POINTS]` - Primitive type.

    - _rgba – [in] Sets blend factor used by `BGFX_STATE_BLEND_FACTOR` and `BGFX_STATE_BLEND_INV_FACTOR` blend modes.

#### State Flags

Write

BGFX_STATE_WRITE_R

  Enable R write.

  Color RGB/alpha/depth write. When it’s not specified write will be disabled.

BGFX_STATE_WRITE_G

  Enable G write.

BGFX_STATE_WRITE_B

  Enable B write.

BGFX_STATE_WRITE_RGB

BGFX_STATE_WRITE_A

  Enable alpha write.

BGFX_STATE_WRITE_Z

  Enable depth write. Enable RGB write.

Depth Test

BGFX_STATE_DEPTH_TEST_LESS

  Enable depth test, less.

  Depth test state. When `BGFX_STATE_DEPTH_` is not specified depth test will be disabled.

BGFX_STATE_DEPTH_TEST_LEQUAL

  Enable depth test, less or equal.

BGFX_STATE_DEPTH_TEST_EQUAL

  Enable depth test, equal.

BGFX_STATE_DEPTH_TEST_GEQUAL

  Enable depth test, greater or equal.

BGFX_STATE_DEPTH_TEST_GREATER

  Enable depth test, greater.

BGFX_STATE_DEPTH_TEST_NOTEQUAL

  Enable depth test, not equal.

BGFX_STATE_DEPTH_TEST_NEVER

  Enable depth test, never.

BGFX_STATE_DEPTH_TEST_ALWAYS

  Enable depth test, always.

Blend Mode

BGFX_STATE_BLEND_ZERO

  0, 0, 0, 0

  Use BGFX_STATE_BLEND_FUNC(_src, _dst) or BGFX_STATE_BLEND_FUNC_SEPARATE(_srcRGB, _dstRGB, _srcA, _dstA) helper macros.

BGFX_STATE_BLEND_ONE

  1, 1, 1, 1

BGFX_STATE_BLEND_SRC_COLOR

  Rs, Gs, Bs, As.

BGFX_STATE_BLEND_INV_SRC_COLOR

  1-Rs, 1-Gs, 1-Bs, 1-As

BGFX_STATE_BLEND_SRC_ALPHA

  As, As, As, As.

BGFX_STATE_BLEND_INV_SRC_ALPHA

  1-As, 1-As, 1-As, 1-As

BGFX_STATE_BLEND_DST_ALPHA

  Ad, Ad, Ad, Ad.

BGFX_STATE_BLEND_INV_DST_ALPHA

  1-Ad, 1-Ad, 1-Ad ,1-Ad

BGFX_STATE_BLEND_DST_COLOR

  Rd, Gd, Bd, Ad.

BGFX_STATE_BLEND_INV_DST_COLOR

  1-Rd, 1-Gd, 1-Bd, 1-Ad

BGFX_STATE_BLEND_SRC_ALPHA_SAT

  f, f, f, 1; f = min(As, 1-Ad)

BGFX_STATE_BLEND_FACTOR

  Blend factor.

BGFX_STATE_BLEND_INV_FACTOR

  1-Blend factor

Blend Equation

BGFX_STATE_BLEND_EQUATION_ADD

  Blend add: src + dst.

  Use BGFX_STATE_BLEND_EQUATION(_equation) or BGFX_STATE_BLEND_EQUATION_SEPARATE(_equationRGB, _equationA) helper macros.

BGFX_STATE_BLEND_EQUATION_SUB

  Blend subtract: src - dst.

BGFX_STATE_BLEND_EQUATION_REVSUB

  Blend reverse subtract: dst - src.

BGFX_STATE_BLEND_EQUATION_MIN

  Blend min: min(src, dst).

BGFX_STATE_BLEND_EQUATION_MAX

  Blend max: max(src, dst).

Primitive Culling

BGFX_STATE_CULL_CW

  Cull clockwise triangles.

  Cull state. When `BGFX_STATE_CULL_*` is not specified culling will be disabled.

BGFX_STATE_CULL_CCW

  Cull counter-clockwise triangles.

Primitive Type

BGFX_STATE_PT_TRISTRIP

  Tristrip.

BGFX_STATE_PT_LINES

  Lines.

BGFX_STATE_PT_LINESTRIP

  Line strip.

BGFX_STATE_PT_POINTS

  Points.

Misc

BGFX_STATE_BLEND_INDEPENDENT

  Enable blend independent.

BGFX_STATE_BLEND_ALPHA_TO_COVERAGE

  Enable alpha to coverage. Default state is write to RGB, alpha, and depth with depth test less enabled, with clockwise culling and MSAA (when writing into MSAA frame buffer, otherwise this flag is ignored).

BGFX_STATE_MSAA

  Enable MSAA rasterization.

  Enable MSAA write when writing into MSAA frame buffer. This flag is ignored when not writing into MSAA frame buffer.

BGFX_STATE_LINEAA

  Enable line AA rasterization.

#### Stencil

void bgfx::setStencil(uint32_t _fstencil, uint32_t _bstencil = BGFX_STENCIL_NONE)

  Set stencil test state.

  Attention

    C99’s equivalent binding is `bgfx_set_stencil`.

  Parameters:

    - _fstencil – [in] Front stencil state.

    - _bstencil – [in] Back stencil state. If back is set to `BGFX_STENCIL_NONE` _fstencil is applied to both front and back facing primitives.

#### Stencil Flags

BGFX_STENCIL_TEST_LESS

  Enable stencil test, less.

#### Scissor

If the Scissor rectangle needs to be changed for every draw call in a View, use bgfx::setScissor. Otherwise, use bgfx::setViewScissor.

uint16_t bgfx::setScissor(uint16_t _x, uint16_t _y, uint16_t _width, uint16_t _height)

  Set scissor for draw primitive. For scissor for all primitives in view see `bgfx::setViewScissor`.

  Attention

    C99’s equivalent binding is `bgfx_set_scissor`.

  Parameters:

    - _x – [in] Position x from the left corner of the window.

    - _y – [in] Position y from the top corner of the window.

    - _width – [in] Width of scissor region.

    - _height – [in] Height of scissor region.

  Returns:

    Scissor cache index.

void bgfx::setScissor(uint16_t _cache = UINT16_MAX)

  Set scissor from cache for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_scissor_cached`.

  Parameters:

    _cache – [in] Index in scissor cache. Passing UINT16_MAX unset primitive scissor and primitive will use view scissor instead.

#### Transform

uint32_t bgfx::allocTransform(Transform *_transform, uint16_t _num)

  Reserve `_num` matrices in internal matrix cache.

  Attention

    Pointer returned can be modified until `bgfx::frame` is called.

  Attention

    C99’s equivalent binding is `bgfx_alloc_transform`.

  Parameters:

    - _transform – [in] Pointer to `Transform` structure.

    - _num – [in] Number of matrices.

  Returns:

    index into matrix cache.

uint32_t bgfx::setTransform(const void *_mtx, uint16_t _num = 1)

  Set model matrix for draw primitive. If it is not called, the model will be rendered with an identity model matrix.

  Attention

    C99’s equivalent binding is `bgfx_set_transform`.

  Parameters:

    - _mtx – [in] Pointer to first matrix in array.

    - _num – [in] Number of matrices in array.

  Returns:

    index into matrix cache in case the same model matrix has to be used for other draw primitive call.

void bgfx::setTransform(uint32_t _cache, uint16_t _num = 1)

  Set model matrix from matrix cache for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_transform_cached`.

  Parameters:

    - _cache – [in] Index in matrix cache.

    - _num – [in] Number of matrices from cache.

#### Conditional Rendering

void bgfx::setCondition(OcclusionQueryHandle _handle, bool _visible)

  Set condition for rendering.

  Attention

    C99’s equivalent binding is `bgfx_set_condition`.

  Parameters:

    - _handle – [in] Occlusion query handle.

    - _visible – [in] Render if occlusion query is visible.

#### Buffers

void bgfx::setIndexBuffer(IndexBufferHandle _handle)

  Set index buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_index_buffer`.

  Parameters:

    _handle – [in] Index buffer.

void bgfx::setIndexBuffer(IndexBufferHandle _handle, uint32_t _firstIndex, uint32_t _numIndices)

  Set index buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_index_buffer`.

  Parameters:

    - _handle – [in] Index buffer.

    - _firstIndex – [in] First index to render.

    - _numIndices – [in] Number of indices to render.

void bgfx::setIndexBuffer(DynamicIndexBufferHandle _handle)

  Set index buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_dynamic_index_buffer`.

  Parameters:

    _handle – [in] Dynamic index buffer.

void bgfx::setIndexBuffer(DynamicIndexBufferHandle _handle, uint32_t _firstIndex, uint32_t _numIndices)

  Set index buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_dynamic_index_buffer`.

  Parameters:

    - _handle – [in] Dynamic index buffer.

    - _firstIndex – [in] First index to render.

    - _numIndices – [in] Number of indices to render.

struct TransientIndexBuffer

  Transient index buffer.

  Attention

    C99’s equivalent binding is `bgfx_transient_index_buffer_t`.

  Public Members

  uint8_t *data

    Pointer to data.

  uint32_t size

    Data size.

  uint32_t startIndex

    First index.

  IndexBufferHandle handle

    Index buffer handle.

  bool isIndex16

    Index buffer format is 16-bits if true, otherwise it is 32-bit.

void bgfx::setIndexBuffer(const TransientIndexBuffer *_tib)

  Set index buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_transient_index_buffer`.

  Parameters:

    _tib – [in] Transient index buffer.

void bgfx::setIndexBuffer(const TransientIndexBuffer *_tib, uint32_t _firstIndex, uint32_t _numIndices)

  Set index buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_transient_index_buffer`.

  Parameters:

    - _tib – [in] Transient index buffer.

    - _firstIndex – [in] First index to render.

    - _numIndices – [in] Number of indices to render.

void bgfx::setVertexBuffer(uint8_t _stream, VertexBufferHandle _handle)

  Set vertex buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_vertex_buffer`.

  Parameters:

    - _stream – [in] Vertex stream.

    - _handle – [in] Vertex buffer.

void bgfx::setVertexBuffer(uint8_t _stream, VertexBufferHandle _handle, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)

  Set vertex buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_vertex_buffer`.

  Parameters:

    - _stream – [in] Vertex stream.

    - _handle – [in] Vertex buffer.

    - _startVertex – [in] First vertex to render.

    - _numVertices – [in] Number of vertices to render.

    - _layoutHandle – [in] Vertex layout for aliasing vertex buffer. If invalid handle is used, vertex layout used for creation of vertex buffer will be used.

void bgfx::setVertexBuffer(uint8_t _stream, DynamicVertexBufferHandle _handle)

  Set vertex buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_dynamic_vertex_buffer`.

  Parameters:

    - _stream – [in] Vertex stream.

    - _handle – [in] Dynamic vertex buffer.

void bgfx::setVertexBuffer(uint8_t _stream, DynamicVertexBufferHandle _handle, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)

  Set vertex buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_dynamic_vertex_buffer`.

  Parameters:

    - _stream – [in] Vertex stream.

    - _handle – [in] Dynamic vertex buffer.

    - _startVertex – [in] First vertex to render.

    - _numVertices – [in] Number of vertices to render.

    - _layoutHandle – [in] Vertex layout for aliasing vertex buffer. If invalid handle is used, vertex layout used for creation of vertex buffer will be used.

struct TransientVertexBuffer

  Transient vertex buffer.

  Attention

    C99’s equivalent binding is `bgfx_transient_vertex_buffer_t`.

  Public Members

  uint8_t *data

    Pointer to data.

  uint32_t size

    Data size.

  uint32_t startVertex

    First vertex.

  uint16_t stride

    Vertex stride.

  VertexBufferHandle handle

    Vertex buffer handle.

  VertexLayoutHandle layoutHandle

    Vertex layout handle.

void bgfx::setVertexBuffer(uint8_t _stream, const TransientVertexBuffer *_tvb)

  Set vertex buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_transient_vertex_buffer`.

  Parameters:

    - _stream – [in] Vertex stream.

    - _tvb – [in] Transient vertex buffer.

void bgfx::setVertexBuffer(uint8_t _stream, const TransientVertexBuffer *_tvb, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)

  Set vertex buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_transient_vertex_buffer`.

  Parameters:

    - _stream – [in] Vertex stream.

    - _tvb – [in] Transient vertex buffer.

    - _startVertex – [in] First vertex to render.

    - _numVertices – [in] Number of vertices to render.

    - _layoutHandle – [in] Vertex layout for aliasing vertex buffer. If invalid handle is used, vertex layout used for creation of vertex buffer will be used.

void bgfx::setVertexCount(uint32_t _numVertices)

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

  Attention

    Availability depends on: `BGFX_CAPS_VERTEX_ID`.

  Attention

    C99’s equivalent binding is `bgfx_set_vertex_count`.

  Parameters:

    _numVertices – [in] Number of vertices.

struct InstanceDataBuffer

  Instance data buffer info.

  Attention

    C99’s equivalent binding is `bgfx_instance_data_buffer_t`.

  Public Members

  uint8_t *data

    Pointer to data.

  uint32_t size

    Data size.

  uint32_t offset

    Offset in vertex buffer.

  uint32_t num

    Number of instances.

  uint16_t stride

    Vertex buffer stride.

  VertexBufferHandle handle

    Vertex buffer object handle.

void bgfx::setInstanceDataBuffer(const InstanceDataBuffer *_idb)

  Set instance data buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_instance_data_buffer`.

  Parameters:

    _idb – [in] Transient instance data buffer.

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

  Set instance data buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_instance_data_buffer`.

  Parameters:

    - _idb – [in] Transient instance data buffer.

    - _start – [in] First instance data.

    - _num – [in] Number of data instances.

void bgfx::setInstanceDataBuffer(VertexBufferHandle _handle, uint32_t _start, uint32_t _num)

  Set instance data buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_instance_data_from_vertex_buffer`.

  Parameters:

    - _handle – [in] Vertex buffer.

    - _start – [in] First instance data.

    - _num – [in] Number of data instances.

void bgfx::setInstanceDataBuffer(DynamicVertexBufferHandle _handle, uint32_t _start, uint32_t _num)

  Set instance data buffer for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_instance_data_from_dynamic_vertex_buffer`.

  Parameters:

    - _handle – [in] Vertex buffer.

    - _start – [in] First instance data.

    - _num – [in] Number of data instances.

void bgfx::setInstanceCount(uint32_t _numInstances)

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

  Attention

    Availability depends on: `BGFX_CAPS_VERTEX_ID`.

  Attention

    C99’s equivalent binding is `bgfx_set_instance_count`.

  Parameters:

    _numInstances – [in] Number of instances.

#### Textures

void bgfx::setTexture(uint8_t _stage, UniformHandle _sampler, TextureHandle _handle, uint32_t _flags = UINT32_MAX)

  Set texture stage for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_texture`.

  Parameters:

    - _stage – [in] Texture unit.

    - _sampler – [in] Program sampler.

    - _handle – [in] Texture handle.

    - _flags – [in] Texture sampling mode. Default value UINT32_MAX uses texture sampling settings from the texture.

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

#### Uniforms

void bgfx::setUniform(UniformHandle _handle, const void *_value, uint16_t _num = 1)

  Set shader uniform parameter for draw primitive.

  Attention

    C99’s equivalent binding is `bgfx_set_uniform`.

  Parameters:

    - _handle – [in] Uniform.

    - _value – [in] Pointer to uniform data.

    - _num – [in] Number of elements. Passing `UINT16_MAX` will use the _num passed on uniform creation.

void bgfx::setViewUniform(ViewId _id, UniformHandle _handle, const void *_value, uint16_t _num = 1)

  Set shader uniform parameter for view.

  Attention

    Uniform must be created with `bgfx::UniformFreq::View` argument.

  Attention

    C99’s equivalent binding is `bgfx_set_view_uniform`.

  Parameters:

    - _id – [in] View id.

    - _handle – [in] Uniform.

    - _value – [in] Pointer to uniform data.

    - _num – [in] Number of elements. Passing `UINT16_MAX` will use the _num passed on uniform creation.

void bgfx::setFrameUniform(UniformHandle _handle, const void *_value, uint16_t _num = 1)

  Set shader uniform parameter for frame.

  Attention

    Uniform must be created with `bgfx::UniformFreq::View` argument.

  Attention

    C99’s equivalent binding is `bgfx_set_frame_uniform`.

  Parameters:

    - _handle – [in] Uniform.

    - _value – [in] Pointer to uniform data.

    - _num – [in] Number of elements. Passing `UINT16_MAX` will use the _num passed on uniform creation.

#### Submit

In Views, all draw commands are executed after blit and compute commands.

void bgfx::submit(ViewId _id, ProgramHandle _program, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)

  Submit primitive for rendering.

  Attention

    C99’s equivalent binding is `bgfx_submit`.

  Parameters:

    - _id – [in] View id.

    - _program – [in] Program.

    - _depth – [in] Depth for sorting.

    - _flags – [in] Discard or preserve states. See `BGFX_DISCARD_*`.

void bgfx::submit(ViewId _id, ProgramHandle _program, OcclusionQueryHandle _occlusionQuery, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)

  Submit primitive with occlusion query for rendering.

  Attention

    C99’s equivalent binding is `bgfx_submit_occlusion_query`.

  Parameters:

    - _id – [in] View id.

    - _program – [in] Program.

    - _occlusionQuery – [in] Occlusion query.

    - _depth – [in] Depth for sorting.

    - _flags – [in] Discard or preserve states. See `BGFX_DISCARD_*`.

void bgfx::submit(ViewId _id, ProgramHandle _program, IndirectBufferHandle _indirectHandle, uint32_t _start = 0, uint32_t _num = 1, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)

  Submit primitive for rendering with index and instance data info from indirect buffer.

  Attention

    Availability depends on: `BGFX_CAPS_DRAW_INDIRECT`.

  Attention

    C99’s equivalent binding is `bgfx_submit_indirect`.

  Parameters:

    - _id – [in] View id.

    - _program – [in] Program.

    - _indirectHandle – [in] Indirect buffer.

    - _start – [in] First element in indirect buffer.

    - _num – [in] Number of draws.

    - _depth – [in] Depth for sorting.

    - _flags – [in] Discard or preserve states. See `BGFX_DISCARD_*`.

void bgfx::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)

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

  Attention

    Availability depends on:`BGFX_CAPS_DRAW_INDIRECT_COUNT`.

  Attention

    C99’s equivalent binding is `bgfx_submit_indirect_count`.

  Parameters:

    - _id – [in] View id.

    - _program – [in] Program.

    - _indirectHandle – [in] Indirect buffer.

    - _start – [in] First element in indirect buffer.

    - _numHandle – [in] Buffer for number of draws. Must be created with `BGFX_BUFFER_INDEX32` and `BGFX_BUFFER_DRAW_INDIRECT`.

    - _numIndex – [in] Element in number buffer.

    - _numMax – [in] Max number of draws.

    - _depth – [in] Depth for sorting.

    - _flags – [in] Discard or preserve states. See `BGFX_DISCARD_*`.

### Compute

Compute state is not preserved between compute dispatches; all state is cleared after calling bgfx::dispatch.

#### Buffers

struct Access

  Access mode enum.

  Attention

    C99’s equivalent binding is `bgfx_access_t`.

  Public Types

  enum Enum

    Access:

    Values:

    enumerator Read

      Read.

    enumerator Write

      Write.

    enumerator ReadWrite

      Read and write.

    enumerator Count

void bgfx::setBuffer(uint8_t _stage, IndexBufferHandle _handle, Access :: Enum _access)

  Set compute index buffer.

  Attention

    C99’s equivalent binding is `bgfx_set_compute_index_buffer`.

  Parameters:

    - _stage – [in] Compute stage.

    - _handle – [in] Index buffer handle.

    - _access – [in] Buffer access. See `Access::Enum`.

void bgfx::setBuffer(uint8_t _stage, VertexBufferHandle _handle, Access :: Enum _access)

  Set compute vertex buffer.

  Attention

    C99’s equivalent binding is `bgfx_set_compute_vertex_buffer`.

  Parameters:

    - _stage – [in] Compute stage.

    - _handle – [in] Vertex buffer handle.

    - _access – [in] Buffer access. See `Access::Enum`.

void bgfx::setBuffer(uint8_t _stage, DynamicIndexBufferHandle _handle, Access :: Enum _access)

  Set compute dynamic index buffer.

  Attention

    C99’s equivalent binding is `bgfx_set_compute_dynamic_index_buffer`.

  Parameters:

    - _stage – [in] Compute stage.

    - _handle – [in] Dynamic index buffer handle.

    - _access – [in] Buffer access. See `Access::Enum`.

void bgfx::setBuffer(uint8_t _stage, DynamicVertexBufferHandle _handle, Access :: Enum _access)

  Set compute dynamic vertex buffer.

  Attention

    C99’s equivalent binding is `bgfx_set_compute_dynamic_vertex_buffer`.

  Parameters:

    - _stage – [in] Compute stage.

    - _handle – [in] Dynamic vertex buffer handle.

    - _access – [in] Buffer access. See `Access::Enum`.

void bgfx::setBuffer(uint8_t _stage, IndirectBufferHandle _handle, Access :: Enum _access)

  Set compute indirect buffer.

  Attention

    C99’s equivalent binding is `bgfx_set_compute_indirect_buffer`.

  Parameters:

    - _stage – [in] Compute stage.

    - _handle – [in] Indirect buffer handle.

    - _access – [in] Buffer access. See `Access::Enum`.

#### Images

void bgfx::setImage(uint8_t _stage, TextureHandle _handle, uint8_t _mip, Access :: Enum _access, TextureFormat :: Enum _format = TextureFormat :: Count )

  Set compute image from texture.

  Attention

    C99’s equivalent binding is `bgfx_set_image`.

  Parameters:

    - _stage – [in] Texture unit.

    - _handle – [in] Texture handle.

    - _mip – [in] Mip level.

    - _access – [in] Texture access. See `Access::Enum`.

    - _format – [in] Texture format. See: `TextureFormat::Enum`.

#### Dispatch

In Views, all draw commands are executed after blit and compute commands.

void bgfx::dispatch(ViewId _id, ProgramHandle _handle, uint32_t _numX = 1, uint32_t _numY = 1, uint32_t _numZ = 1, uint8_t _flags = BGFX_DISCARD_ALL)

  Dispatch compute.

  Attention

    C99’s equivalent binding is `bgfx_dispatch`.

  Parameters:

    - _id – [in] View id.

    - _handle – [in] Compute program.

    - _numX – [in] Number of groups X.

    - _numY – [in] Number of groups Y.

    - _numZ – [in] Number of groups Z.

    - _flags – [in] Discard or preserve states. See `BGFX_DISCARD_*`.

void bgfx::dispatch(ViewId _id, ProgramHandle _handle, IndirectBufferHandle _indirectHandle, uint32_t _start = 0, uint32_t _num = 1, uint8_t _flags = BGFX_DISCARD_ALL)

  Dispatch compute indirect.

  Attention

    C99’s equivalent binding is `bgfx_dispatch_indirect`.

  Parameters:

    - _id – [in] View id.

    - _handle – [in] Compute program.

    - _indirectHandle – [in] Indirect buffer.

    - _start – [in] First element in indirect buffer.

    - _num – [in] Number of dispatches.

    - _flags – [in] Discard or preserve states. See `BGFX_DISCARD_*`.

### Blit

In Views, all draw commands are executed after blit and compute commands.

void bgfx::blit(ViewId _id, TextureHandle _dst, uint16_t _dstX, uint16_t _dstY, TextureHandle _src, uint16_t _srcX = 0, uint16_t _srcY = 0, uint16_t _width = UINT16_MAX, uint16_t _height = UINT16_MAX)

  Blit 2D texture region between two 2D textures.

  Attention

    Destination texture must be created with `BGFX_TEXTURE_BLIT_DST` flag.

  Attention

    Availability depends on: `BGFX_CAPS_TEXTURE_BLIT`.

  Attention

    C99’s equivalent binding is `bgfx_blit`.

  Parameters:

    - _id – [in] View id.

    - _dst – [in] Destination texture handle.

    - _dstX – [in] Destination texture X position.

    - _dstY – [in] Destination texture Y position.

    - _src – [in] Source texture handle.

    - _srcX – [in] Source texture X position.

    - _srcY – [in] Source texture Y position.

    - _width – [in] Width of region.

    - _height – [in] Height of region.

void bgfx::blit(ViewId _id, TextureHandle _dst, uint8_t _dstMip, uint16_t _dstX, uint16_t _dstY, uint16_t _dstZ, TextureHandle _src, uint8_t _srcMip = 0, uint16_t _srcX = 0, uint16_t _srcY = 0, uint16_t _srcZ = 0, uint16_t _width = UINT16_MAX, uint16_t _height = UINT16_MAX, uint16_t _depth = UINT16_MAX)

  Blit texture region between two textures.

  Attention

    Destination texture must be created with `BGFX_TEXTURE_BLIT_DST` flag.

  Attention

    Availability depends on: `BGFX_CAPS_TEXTURE_BLIT`.

  Attention

    C99’s equivalent binding is `bgfx_blit`.

  Parameters:

    - _id – [in] View id.

    - _dst – [in] Destination texture handle.

    - _dstMip – [in] Destination texture mip level.

    - _dstX – [in] Destination texture X position.

    - _dstY – [in] Destination texture Y position.

    - _dstZ – [in] If texture is 2D this argument should be 0. If destination texture is cube this argument represents destination texture cube face. For 3D texture this argument represents destination texture Z position.

    - _src – [in] Source texture handle.

    - _srcMip – [in] Source texture mip level.

    - _srcX – [in] Source texture X position.

    - _srcY – [in] Source texture Y position.

    - _srcZ – [in] If texture is 2D this argument should be 0. If source texture is cube this argument represents source texture cube face. For 3D texture this argument represents source texture Z position.

    - _width – [in] Width of region.

    - _height – [in] Height of region.

    - _depth – [in] If texture is 3D this argument represents depth of region, otherwise it’s unused.

## Resources

struct Memory

  Memory must be obtained by calling `bgfx::alloc`, `bgfx::copy`, or `bgfx::makeRef`.

  Attention

    It is illegal to create this structure on stack and pass it to any bgfx API.

  Attention

    C99’s equivalent binding is `bgfx_memory_t`.

  Public Members

  uint8_t *data

    Pointer to data.

  uint32_t size

    Data size.

const Memory *bgfx::alloc(uint32_t _size)

  Allocate buffer to pass to bgfx calls. Data will be freed inside bgfx.

  Attention

    C99’s equivalent binding is `bgfx_alloc`.

  Parameters:

    _size – [in] Size to allocate.

const Memory *bgfx::copy(const void *_data, uint32_t _size)

  Allocate buffer and copy data into it. Data will be freed inside bgfx.

  Attention

    C99’s equivalent binding is `bgfx_copy`.

  Parameters:

    - _data – [in] Pointer to data to be copied.

    - _size – [in] Size of data to be copied.

const Memory *bgfx::makeRef(const void *_data, uint32_t _size, ReleaseFn _releaseFn = NULL, void *_userData = NULL)

  Make reference to data to pass to bgfx. Unlike `bgfx::alloc`, this call doesn’t allocate memory for data. It just copies the _data pointer. You can pass `ReleaseFn` function pointer to release this memory after it’s consumed, otherwise you must make sure _data is available for at least 2 `bgfx::frame` calls. `ReleaseFn` function must be able to be called from any thread.

  Attention

    Data passed must be available for at least 2 `bgfx::frame` calls.

  Attention

    C99’s equivalent bindings are `bgfx_make_ref`, `bgfx_make_ref_release`.

  Parameters:

    - _data – [in] Pointer to data.

    - _size – [in] Size of data.

    - _releaseFn – [in] Callback function to release memory after use.

    - _userData – [in] User data to be passed to callback function.

### Shaders and Programs

Note

Shaders must be compiled with offline command line too shaderc.

ShaderHandle bgfx::createShader(const Memory *_mem)

  Create shader from memory buffer.

  Remark

  Shader binary is obtained by compiling shader offline with shaderc command line tool.

  Attention

    C99’s equivalent binding is `bgfx_create_shader`.

  Returns:

    Shader handle.

uint16_t bgfx::getShaderUniforms(ShaderHandle _handle, UniformHandle *_uniforms = NULL, uint16_t _max = 0)

  Returns the number of uniforms and uniform handles used inside a shader.

  Remark

  Only non-predefined uniforms are returned.

  Attention

    C99’s equivalent binding is `bgfx_get_shader_uniforms`.

  Parameters:

    - _handle – [in] Shader handle.

    - _uniforms – [in] UniformHandle array where data will be stored.

    - _max – [in] Maximum capacity of array.

  Returns:

    Number of uniforms used by shader.

void bgfx::destroy(ShaderHandle _handle)

  Destroy shader. Once a shader program is created with _handle, it is safe to destroy that shader.

  Attention

    C99’s equivalent binding is `bgfx_destroy_shader`.

  Parameters:

    _handle – [in] Shader handle.

ProgramHandle bgfx::createProgram(ShaderHandle _vsh, ShaderHandle _fsh, bool _destroyShaders = false)

  Create program with vertex and fragment shaders.

  Attention

    C99’s equivalent binding is `bgfx_create_program`.

  Parameters:

    - _vsh – [in] Vertex shader.

    - _fsh – [in] Fragment shader.

    - _destroyShaders – [in] If true, shaders will be destroyed when program is destroyed.

  Returns:

    Program handle if vertex shader output and fragment shader input are matching, otherwise returns invalid program handle.

ProgramHandle bgfx::createProgram(ShaderHandle _csh, bool _destroyShader = false)

  Create program with compute shader.

  Attention

    C99’s equivalent binding is `bgfx_create_compute_program`.

  Parameters:

    - _csh – [in] Compute shader.

    - _destroyShader – [in] If true, shader will be destroyed when program is destroyed.

  Returns:

    Program handle.

void bgfx::destroy(ProgramHandle _handle)

  Destroy program.

  Attention

    C99’s equivalent binding is `bgfx_destroy_program`.

  Parameters:

    _handle – [in] Program handle.

### Uniforms

struct UniformType

  Uniform type enum.

  Attention

    C99’s equivalent binding is `bgfx_uniform_type_t`.

  Public Types

  enum Enum

    Uniform types:

    Values:

    enumerator Sampler

      Sampler.

    enumerator End

      Reserved, do not use.

    enumerator Vec4

      4 floats vector.

    enumerator Mat3

      3x3 matrix.

    enumerator Mat4

      4x4 matrix.

    enumerator Count

UniformHandle bgfx::createUniform(const char *_name, UniformType :: Enum _type, uint16_t _num = 1)

  Create shader uniform parameter.

  - `u_modelViewProj mat4` - concatenated model view projection matrix.

    - `u_alphaRef float` - alpha reference value for alpha test.

  Remark

  1. Uniform names are unique. It’s valid to call `bgfx::createUniform` multiple times with the same uniform name. The library will always return the same handle, but the handle reference count will be incremented. This means that the same number of `bgfx::destroyUniform` must be called to properly destroy the uniform.

  2. Predefined uniforms (declared in `bgfx_shader.sh`):

     - `u_viewRect vec4(x, y, width, height)` - view rectangle for current view, in pixels.

     - `u_viewTexel vec4(1.0/width, 1.0/height, undef, undef)` - inverse width and height

     - `u_view mat4` - view matrix

     - `u_invView mat4` - inverted view matrix

     - `u_proj mat4` - projection matrix

     - `u_invProj mat4` - inverted projection matrix

     - `u_viewProj mat4` - concatenated view projection matrix

     - `u_invViewProj mat4` - concatenated inverted view projection matrix

     - `u_model mat4[BGFX_CONFIG_MAX_BONES]` - array of model matrices.

     - `u_modelView mat4` - concatenated model view matrix, only first model matrix from array is used.

  Attention

    C99’s equivalent binding is `bgfx_create_uniform`.

  Parameters:

    - _name – [in] Uniform name in shader.

    - _type – [in] Type of uniform (See: `bgfx::UniformType`).

    - _num – [in] Number of elements in array.

  Returns:

    Handle to uniform object.

struct UniformFreq

  Uniform frequency enum.

  Attention

    C99’s equivalent binding is `bgfx_bgfx_uniform_freq_t`.

  Public Types

  enum Enum

    Uniform frequency:

    Values:

    enumerator Draw

      Changing per draw call.

    enumerator View

      Changing per view.

    enumerator Frame

      Changing per frame.

    enumerator Count

UniformHandle bgfx::createUniform(const char *_name, UniformFreq :: Enum _freq, UniformType :: Enum _type, uint16_t _num = 1)

  Create shader uniform parameter.

  Remark

  1. Uniform names are unique. It’s valid to call `bgfx::createUniform` multiple times with the same uniform name. The library will always return the same handle, but the handle reference count will be incremented. This means that the same number of `bgfx::destroyUniform` must be called to properly destroy the uniform.

  2. Predefined uniforms (declared in `bgfx_shader.sh`):

     - `u_viewRect vec4(x, y, width, height)` - view rectangle for current view, in pixels.

     - `u_viewTexel vec4(1.0/width, 1.0/height, undef, undef)` - inverse width and height

     - `u_view mat4` - view matrix

     - `u_invView mat4` - inverted view matrix

     - `u_proj mat4` - projection matrix

     - `u_invProj mat4` - inverted projection matrix

     - `u_viewProj mat4` - concatenated view projection matrix

     - `u_invViewProj mat4` - concatenated inverted view projection matrix

     - `u_model mat4[BGFX_CONFIG_MAX_BONES]` - array of model matrices.

     - `u_modelView mat4` - concatenated model view matrix, only first model matrix from array is used.

     - `u_invModelView mat4` - inverted concatenated model view matrix.

     - `u_modelViewProj mat4` - concatenated model view projection matrix.

     - `u_alphaRef float` - alpha reference value for alpha test.

  Attention

    C99’s equivalent binding is `bgfx_create_uniform_with_freq`.

  Parameters:

    - _name – [in] Uniform name in shader.

    - _freq – [in] Uniform change frequency (See: `bgfx::UniformFreq`).

    - _type – [in] Type of uniform (See: `bgfx::UniformType`).

    - _num – [in] Number of elements in array.

  Returns:

    Handle to uniform object.

struct UniformInfo

  Uniform info.

  Attention

    C99’s equivalent binding is `bgfx_uniform_info_t`.

  Public Members

  char name[256]

    Uniform name.

  UniformType :: Enum type

    Uniform type.

  uint16_t num

    Number of elements in array.

void bgfx::getUniformInfo(UniformHandle _handle, UniformInfo &_info)

  Retrieve uniform info.

  Attention

    C99’s equivalent binding is `bgfx_get_uniform_info`.

  Parameters:

    - _handle – [in] Handle to uniform object.

    - _info – [out] Uniform info.

void bgfx::destroy(UniformHandle _handle)

  Destroy shader uniform parameter.

  Attention

    C99’s equivalent binding is `bgfx_destroy_uniform`.

  Parameters:

    _handle – [in] Handle to uniform object.

### Vertex Buffers

VertexLayoutHandle bgfx::createVertexLayout(const VertexLayout &_layout)

  Create vertex layout.

  Attention

    C99’s equivalent binding is `bgfx_create_vertex_layout`.

void bgfx::destroy(VertexLayoutHandle _handle)

  Destroy vertex layout.

  Attention

    C99’s equivalent binding is `bgfx_destroy_vertex_layout`.

VertexBufferHandle bgfx::createVertexBuffer(const Memory *_mem, const VertexLayout &_layout, uint16_t _flags = BGFX_BUFFER_NONE)

  Create static vertex buffer.

  Attention

    C99’s equivalent binding is `bgfx_create_vertex_buffer`.

  Parameters:

    - _mem – [in] Vertex buffer data.

    - _layout – [in] Vertex layout.

    - _flags – [in] Buffer creation flags.

      - `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. When buffer is created with `BGFX_BUFFER_COMPUTE_WRITE` flag it 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 buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.

      - `BGFX_BUFFER_INDEX32` - Buffer is using 32-bit indices. This flag has effect only on index buffers.

  Returns:

    Static vertex buffer handle.

void bgfx::setName(VertexBufferHandle _handle, const char *_name, int32_t _len = INT32_MAX)

  Set static vertex buffer debug name.

  Attention

    C99’s equivalent binding is `bgfx_set_vertex_buffer_name`.

  Parameters:

    - _handle – [in] Static vertex buffer handle.

    - _name – [in] Static vertex buffer name.

    - _len – [in] Static vertex buffer name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.

void bgfx::destroy(VertexBufferHandle _handle)

  Destroy static vertex buffer.

  Attention

    C99’s equivalent binding is `bgfx_destroy_vertex_buffer`.

  Parameters:

    _handle – [in] Static vertex buffer handle.

struct VertexLayout

  Vertex layout.

  Attention

    C99’s equivalent binding is `bgfx_vertex_layout_t`.

  Public Functions

  VertexLayout &begin( RendererType :: Enum _renderer = RendererType :: Noop )

    Start VertexLayout.

    Attention

      C99’s equivalent binding is `bgfx_vertex_layout_begin`.

    Parameters:

      _renderer – [in] Renderer backend type. See: `bgfx::RendererType`

    Returns:

      Returns itself.

  void end()

    End VertexLayout.

    Attention

      C99’s equivalent binding is `bgfx_vertex_layout_end`.

  VertexLayout &add( Attrib :: Enum _attrib, uint8_t _num, AttribType :: Enum _type, bool _normalized = false, bool _asInt = false)

    Add attribute to VertexLayout.

    Remark

    Must be called between begin/end.

    Attention

      C99’s equivalent binding is `bgfx_vertex_layout_add`.

    Parameters:

      - _attrib – [in] Attribute semantics. See: `bgfx::Attrib`

      - _num – [in] Number of elements 1, 2, 3 or 4.

      - _type – [in] Element type.

      - _normalized – [in] When using fixed point AttribType (f.e. Uint8) value will be normalized for vertex shader usage. When normalized is set to true, AttribType::Uint8 value in range 0-255 will be in range 0.0-1.0 in vertex shader.

      - _asInt – [in] Packaging rule for vertexPack, vertexUnpack, and vertexConvert for AttribType::Uint8 and AttribType::Int16. Unpacking code must be implemented inside vertex shader.

    Returns:

      Returns itself.

  VertexLayout &skip(uint8_t _num)

    Skip _num bytes in vertex stream.

    Attention

      C99’s equivalent binding is `bgfx_vertex_layout_skip`.

    Returns:

      Returns itself.

  void decode( Attrib :: Enum _attrib, uint8_t &_num, AttribType :: Enum &_type, bool &_normalized, bool &_asInt) const

    Decode attribute.

    Attention

      C99’s equivalent binding is `bgfx_vertex_layout_decode`.

  inline bool has( Attrib :: Enum _attrib) const

    Returns `true` if VertexLayout contains attribute.

    Attention

      C99’s equivalent binding is `bgfx_vertex_layout_has`.

    Parameters:

      _attrib – [in] Attribute semantics. See: `bgfx::Attrib`

    Returns:

      True if VertexLayout contains attribute.

  inline uint16_t getOffset( Attrib :: Enum _attrib) const

    Returns relative attribute offset from the vertex.

    Parameters:

      _attrib – [in] Attribute semantics. See: `bgfx::Attrib`

    Returns:

      Relative attribute offset from the vertex.

  inline uint16_t getStride() const

    Returns vertex stride.

    Returns:

      Vertex stride.

  inline uint32_t getSize(uint32_t _num) const

    Returns size of vertex buffer for number of vertices.

    Parameters:

      _num – [in] Number of vertices.

    Returns:

      Size of vertex buffer for number of vertices.

  Public Members

  uint32_t m_hash

    Hash.

  uint16_t m_stride

    Stride.

  uint16_t m_offset[ Attrib :: Count ]

    Attribute offsets.

  uint16_t m_attributes[ Attrib :: Count ]

    Used attributes.

struct Attrib

  Vertex attribute enum.

  Attention

    C99’s equivalent binding is `bgfx_attrib_t`.

  Public Types

  enum Enum

    Corresponds to vertex shader attribute.

    Values:

    enumerator Position

      a_position

    enumerator Normal

      a_normal

    enumerator Tangent

      a_tangent

    enumerator Bitangent

      a_bitangent

    enumerator Color0

      a_color0

    enumerator Color1

      a_color1

    enumerator Color2

      a_color2

    enumerator Color3

      a_color3

    enumerator Indices

      a_indices

    enumerator Weight

      a_weight

    enumerator TexCoord0

      a_texcoord0

    enumerator TexCoord1

      a_texcoord1

    enumerator TexCoord2

      a_texcoord2

    enumerator TexCoord3

      a_texcoord3

    enumerator TexCoord4

      a_texcoord4

    enumerator TexCoord5

      a_texcoord5

    enumerator TexCoord6

      a_texcoord6

    enumerator TexCoord7

      a_texcoord7

    enumerator Count

struct AttribType

  Vertex attribute type enum.

  Attention

    C99’s equivalent binding is `bgfx_attrib_type_t`.

  Public Types

  enum Enum

    Attribute types:

    Values:

    enumerator Uint8

      Uint8.

    enumerator Uint10

      Uint10, availability depends on: `BGFX_CAPS_VERTEX_ATTRIB_UINT10`.

    enumerator Int16

      Int16.

    enumerator Half

      Half, availability depends on: `BGFX_CAPS_VERTEX_ATTRIB_HALF`.

    enumerator Float

      Float.

    enumerator Count

DynamicVertexBufferHandle bgfx::createDynamicVertexBuffer(uint32_t _num, const VertexLayout &_layout, uint16_t _flags = BGFX_BUFFER_NONE)

  Create empty dynamic vertex buffer.

  Attention

    C99’s equivalent binding is `bgfx_create_dynamic_vertex_buffer`.

  Parameters:

    - _num – [in] Number of vertices.

    - _layout – [in] Vertex layout.

    - _flags – [in] Buffer creation flags.

      - `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. When buffer is created with `BGFX_BUFFER_COMPUTE_WRITE` flag it 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 buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.

      - `BGFX_BUFFER_INDEX32` - Buffer is using 32-bit indices. This flag has effect only on index buffers.

  Returns:

    Dynamic vertex buffer handle.

DynamicVertexBufferHandle bgfx::createDynamicVertexBuffer(const Memory *_mem, const VertexLayout &_layout, uint16_t _flags = BGFX_BUFFER_NONE)

  Create dynamic vertex buffer and initialize it.

  Attention

    C99’s equivalent binding is `bgfx_create_dynamic_vertex_buffer_mem`.

  Parameters:

    - _mem – [in] Vertex buffer data.

    - _layout – [in] Vertex layout.

    - _flags – [in] Buffer creation flags.

      - `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. When buffer is created with `BGFX_BUFFER_COMPUTE_WRITE` flag it 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 buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.

      - `BGFX_BUFFER_INDEX32` - Buffer is using 32-bit indices. This flag has effect only on index buffers.

  Returns:

    Dynamic vertex buffer handle.

void bgfx::update(DynamicVertexBufferHandle _handle, uint32_t _startVertex, const Memory *_mem)

  Update dynamic vertex buffer.

  Attention

    C99’s equivalent binding is `bgfx_update_dynamic_vertex_buffer`.

  Parameters:

    - _handle – [in] Dynamic vertex buffer handle.

    - _startVertex – [in] Start vertex.

    - _mem – [in] Vertex buffer data.

void bgfx::destroy(DynamicVertexBufferHandle _handle)

  Destroy dynamic vertex buffer.

  Attention

    C99’s equivalent binding is `bgfx_destroy_dynamic_vertex_buffer`.

  Parameters:

    _handle – [in] Dynamic vertex buffer handle.

uint32_t bgfx::getAvailTransientVertexBuffer(uint32_t _num, const VertexLayout &_layout)

  Returns number of requested or maximum available vertices.

  Attention

    C99’s equivalent binding is `bgfx_get_avail_transient_vertex_buffer`.

  Parameters:

    - _num – [in] Number of required vertices.

    - _layout – [in] Vertex layout.

void bgfx::allocTransientVertexBuffer( TransientVertexBuffer *_tvb, uint32_t _num, const VertexLayout &_layout)

  Allocate transient vertex buffer.

  Attention

    C99’s equivalent binding is `bgfx_alloc_transient_vertex_buffer`.

  Parameters:

    - _tvb – [out] TransientVertexBuffer structure will be filled, and will be valid for the duration of frame, and can be reused for multiple draw calls.

    - _num – [in] Number of vertices to allocate.

    - _layout – [in] Vertex layout.

### Index Buffers

IndexBufferHandle bgfx::createIndexBuffer(const Memory *_mem, uint16_t _flags = BGFX_BUFFER_NONE)

  Create static index buffer.

  Attention

    C99’s equivalent binding is `bgfx_create_index_buffer`.

  Parameters:

    - _mem – [in] Index buffer data.

    - _flags – [in] Buffer creation flags.

      - `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. When buffer is created with `BGFX_BUFFER_COMPUTE_WRITE` flag it 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 buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.

      - `BGFX_BUFFER_INDEX32` - Buffer is using 32-bit indices. This flag has effect only on index buffers.

void bgfx::setName(IndexBufferHandle _handle, const char *_name, int32_t _len = INT32_MAX)

  Set static index buffer debug name.

  Attention

    C99’s equivalent binding is `bgfx_set_index_buffer_name`.

  Parameters:

    - _handle – [in] Static index buffer handle.

    - _name – [in] Static index buffer name.

    - _len – [in] Static index buffer name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.

void bgfx::destroy(IndexBufferHandle _handle)

  Destroy static index buffer.

  Attention

    C99’s equivalent binding is `bgfx_destroy_index_buffer`.

  Parameters:

    _handle – [in] Static index buffer handle.

DynamicIndexBufferHandle bgfx::createDynamicIndexBuffer(uint32_t _num, uint16_t _flags = BGFX_BUFFER_NONE)

  Create empty dynamic index buffer.

  Attention

    C99’s equivalent binding is `bgfx_create_dynamic_index_buffer`.

  Parameters:

    - _num – [in] Number of indices.

    - _flags – [in] Buffer creation flags.

      - `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. When buffer is created with `BGFX_BUFFER_COMPUTE_WRITE` flag it 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 buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.

      - `BGFX_BUFFER_INDEX32` - Buffer is using 32-bit indices. This flag has effect only on index buffers.

  Returns:

    Dynamic index buffer handle.

DynamicIndexBufferHandle bgfx::createDynamicIndexBuffer(const Memory *_mem, uint16_t _flags = BGFX_BUFFER_NONE)

  Create a dynamic index buffer and initialize it.

  Attention

    C99’s equivalent binding is `bgfx_create_dynamic_index_buffer_mem`.

  Parameters:

    - _mem – [in] Index buffer data.

    - _flags – [in] Buffer creation flags.

      - `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. When buffer is created with `BGFX_BUFFER_COMPUTE_WRITE` flag it 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 buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.

      - `BGFX_BUFFER_INDEX32` - Buffer is using 32-bit indices. This flag has effect only on index buffers.

  Returns:

    Dynamic index buffer handle.

void bgfx::update(DynamicIndexBufferHandle _handle, uint32_t _startIndex, const Memory *_mem)

  Update dynamic index buffer.

  Attention

    C99’s equivalent binding is `bgfx_update_dynamic_index_buffer`.

  Parameters:

    - _handle – [in] Dynamic index buffer handle.

    - _startIndex – [in] Start index.

    - _mem – [in] Index buffer data.

void bgfx::destroy(DynamicIndexBufferHandle _handle)

  Destroy dynamic index buffer.

  Attention

    C99’s equivalent binding is `bgfx_destroy_dynamic_index_buffer`.

  Parameters:

    _handle – [in] Dynamic index buffer handle.

uint32_t bgfx::getAvailTransientIndexBuffer(uint32_t _num, bool _index32 = false)

  Returns number of requested or maximum available indices.

  Attention

    C99’s equivalent binding is `bgfx_get_avail_transient_index_buffer`.

  Parameters:

    - _num – [in] Number of required indices.

    - _index32 – [in] Set to `true` if input indices will be 32-bit.

void bgfx::allocTransientIndexBuffer( TransientIndexBuffer *_tib, uint32_t _num, bool _index32 = false)

  Allocate transient index buffer.

  Attention

    C99’s equivalent binding is `bgfx_alloc_transient_index_buffer`.

  Parameters:

    - _tib – [out] TransientIndexBuffer structure will be filled, and will be valid for the duration of frame, and can be reused for multiple draw calls.

    - _num – [in] Number of indices to allocate.

    - _index32 – [in] Set to `true` if input indices will be 32-bit.

### Textures

struct TextureFormat

  Texture format enum.

  Notation:

        RGBA16S
        ^   ^ ^
        |   | +-- [ ]Unorm
        |   |     [F]loat
        |   |     [S]norm
        |   |     [I]nt
        |   |     [U]int
        |   +---- Number of bits per component
        +-------- Components

  Attention

    Availability depends on Caps (see: formats).

  Attention

    C99’s equivalent binding is `bgfx_texture_format_t`.

  Public Types

  enum Enum

    Texture formats:

    Values:

    enumerator BC1

      DXT1 R5G6B5A1.

    enumerator BC2

      DXT3 R5G6B5A4.

    enumerator BC3

      DXT5 R5G6B5A8.

    enumerator BC4

      LATC1/ATI1 R8.

    enumerator BC5

      LATC2/ATI2 RG8.

    enumerator BC6H

      BC6H RGB16F.

    enumerator BC7

      BC7 RGB 4-7 bits per color channel, 0-8 bits alpha.

    enumerator ETC1

      ETC1 RGB8.

    enumerator ETC2

      ETC2 RGB8.

    enumerator ETC2A

      ETC2 RGBA8.

    enumerator ETC2A1

      ETC2 RGB8A1.

    enumerator EACR11

      EAC R11 UNORM.

    enumerator EACR11S

      EAC R11 SNORM.

    enumerator EACRG11

      EAC RG11 UNORM.

    enumerator EACRG11S

      EAC RG11 SNORM.

    enumerator PTC12

      PVRTC1 RGB 2BPP.

    enumerator PTC14

      PVRTC1 RGB 4BPP.

    enumerator PTC12A

      PVRTC1 RGBA 2BPP.

    enumerator PTC14A

      PVRTC1 RGBA 4BPP.

    enumerator PTC22

      PVRTC2 RGBA 2BPP.

    enumerator PTC24

      PVRTC2 RGBA 4BPP.

    enumerator ATC

      ATC RGB 4BPP.

    enumerator ATCE

      ATCE RGBA 8 BPP explicit alpha.

    enumerator ATCI

      ATCI RGBA 8 BPP interpolated alpha.

    enumerator ASTC4x4

      ASTC 4x4 8.0 BPP.

    enumerator ASTC5x4

      ASTC 5x4 6.40 BPP.

    enumerator ASTC5x5

      ASTC 5x5 5.12 BPP.

    enumerator ASTC6x5

      ASTC 6x5 4.27 BPP.

    enumerator ASTC6x6

      ASTC 6x6 3.56 BPP.

    enumerator ASTC8x5

      ASTC 8x5 3.20 BPP.

    enumerator ASTC8x6

      ASTC 8x6 2.67 BPP.

    enumerator ASTC8x8

      ASTC 8x8 2.00 BPP.

    enumerator ASTC10x5

      ASTC 10x5 2.56 BPP.

    enumerator ASTC10x6

      ASTC 10x6 2.13 BPP.

    enumerator ASTC10x8

      ASTC 10x8 1.60 BPP.

    enumerator ASTC10x10

      ASTC 10x10 1.28 BPP.

    enumerator ASTC12x10

      ASTC 12x10 1.07 BPP.

    enumerator ASTC12x12

      ASTC 12x12 0.89 BPP.

    enumerator Unknown
    enumerator R1
    enumerator A8
    enumerator R8
    enumerator R8I
    enumerator R8U
    enumerator R8S
    enumerator R16
    enumerator R16I
    enumerator R16U
    enumerator R16F
    enumerator R16S
    enumerator R32I
    enumerator R32U
    enumerator R32F
    enumerator RG8
    enumerator RG8I
    enumerator RG8U
    enumerator RG8S
    enumerator RG16
    enumerator RG16I
    enumerator RG16U
    enumerator RG16F
    enumerator RG16S
    enumerator RG32I
    enumerator RG32U
    enumerator RG32F
    enumerator RGB8
    enumerator RGB8I
    enumerator RGB8U
    enumerator RGB8S
    enumerator RGB9E5F
    enumerator BGRA8
    enumerator RGBA8
    enumerator RGBA8I
    enumerator RGBA8U
    enumerator RGBA8S
    enumerator RGBA16
    enumerator RGBA16I
    enumerator RGBA16U
    enumerator RGBA16F
    enumerator RGBA16S
    enumerator RGBA32I
    enumerator RGBA32U
    enumerator RGBA32F
    enumerator B5G6R5
    enumerator R5G6B5
    enumerator BGRA4
    enumerator RGBA4
    enumerator BGR5A1
    enumerator RGB5A1
    enumerator RGB10A2
    enumerator RG11B10F
    enumerator UnknownDepth
    enumerator D16
    enumerator D24
    enumerator D24S8
    enumerator D32
    enumerator D16F
    enumerator D24F
    enumerator D32F
    enumerator D0S8
    enumerator Count

Texture Flags

BGFX_TEXTURE_MSAA_SAMPLE

  Texture will be used for MSAA sampling.

BGFX_TEXTURE_RT

  Render target no MSAA.

BGFX_TEXTURE_COMPUTE_WRITE

  Texture will be used for compute write.

BGFX_TEXTURE_SRGB

  Sample texture as sRGB.

BGFX_TEXTURE_BLIT_DST

  Texture will be used as blit destination.

BGFX_TEXTURE_READ_BACK

  Texture will be used for read back from GPU.

BGFX_TEXTURE_RT_MSAA_X2

  Render target MSAAx2 mode.

BGFX_TEXTURE_RT_MSAA_X4

  Render target MSAAx4 mode.

BGFX_TEXTURE_RT_MSAA_X8

  Render target MSAAx8 mode.

BGFX_TEXTURE_RT_MSAA_X16

  Render target MSAAx16 mode.

BGFX_TEXTURE_RT_WRITE_ONLY

  Render target will be used for writing.

bool bgfx::isTextureValid(uint16_t _depth, bool _cubeMap, uint16_t _numLayers, TextureFormat :: Enum _format, uint64_t _flags)

  Validate texture parameters.

  Attention

    C99’s equivalent binding is `bgfx_is_texture_valid`.

  Parameters:

    - _depth – [in] Depth dimension of volume texture.

    - _cubeMap – [in] Indicates that texture contains cubemap.

    - _numLayers – [in] Number of layers in texture array.

    - _format – [in] Texture format. See: `TextureFormat::Enum`.

    - _flags – [in] Texture flags. See `BGFX_TEXTURE_*`.

  Returns:

    True if a texture with the same parameters can be created.

struct TextureInfo

  Texture info.

  Attention

    C99’s equivalent binding is `bgfx_texture_info_t`.

  Public Members

  TextureFormat :: Enum format

    Texture format.

  uint32_t storageSize

    Total amount of bytes required to store texture.

  uint16_t width

    Texture width.

  uint16_t height

    Texture height.

  uint16_t depth

    Texture depth.

  uint16_t numLayers

    Number of layers in texture array.

  uint8_t numMips

    Number of MIP maps.

  uint8_t bitsPerPixel

    Format bits per pixel.

  bool cubeMap

    Texture is cubemap.

void bgfx::calcTextureSize( TextureInfo &_info, uint16_t _width, uint16_t _height, uint16_t _depth, bool _cubeMap, bool _hasMips, uint16_t _numLayers, TextureFormat :: Enum _format)

  Calculate amount of memory required for texture.

  Attention

    C99’s equivalent binding is `bgfx_calc_texture_size`.

  Parameters:

    - _info – [out] Resulting texture info structure. See: `TextureInfo`.

    - _width – [in] Width.

    - _height – [in] Height.

    - _depth – [in] Depth dimension of volume texture.

    - _cubeMap – [in] Indicates that texture contains cubemap.

    - _hasMips – [in] Indicates that texture contains full mip-map chain.

    - _numLayers – [in] Number of layers in texture array.

    - _format – [in] Texture format. See: `TextureFormat::Enum`.

TextureHandle bgfx::createTexture(const Memory *_mem, uint64_t _flags = BGFX_TEXTURE_NONE | BGFX_SAMPLER_NONE, uint8_t _skip = 0, TextureInfo *_info = NULL)

  Create texture from memory buffer.

  Attention

    C99’s equivalent binding is `bgfx_create_texture`.

  Parameters:

    - _mem – [in] DDS, KTX or PVR texture data.

    - _flags – [in] 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.

    - _skip – [in] Skip top level mips when parsing texture.

    - _info – [out] When non-`NULL` is specified it returns parsed texture information.

  Returns:

    Texture handle.

TextureHandle bgfx::createTexture2D(uint16_t _width, uint16_t _height, bool _hasMips, uint16_t _numLayers, TextureFormat :: Enum _format, uint64_t _flags = BGFX_TEXTURE_NONE | BGFX_SAMPLER_NONE, const Memory *_mem = NULL)

  Create 2D texture.

  Attention

    C99’s equivalent binding is `bgfx_create_texture_2d`.

  Parameters:

    - _width – [in] Width.

    - _height – [in] Height.

    - _hasMips – [in] Indicates that texture contains full mip-map chain.

    - _numLayers – [in] Number of layers in texture array. Must be 1 if caps `BGFX_CAPS_TEXTURE_2D_ARRAY` flag is not set.

    - _format – [in] Texture format. See: `TextureFormat::Enum`.

    - _flags – [in] 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.

    - _mem – [in] Texture data. If `_mem` is non-NULL, created texture will be immutable. If `_mem` is NULL content of the texture is uninitialized. When `_numLayers` is more than 1, expected memory layout is texture and all mips together for each array element.

TextureHandle bgfx::createTexture2D(BackbufferRatio::Enum _ratio, bool _hasMips, uint16_t _numLayers, TextureFormat :: Enum _format, uint64_t _flags = BGFX_TEXTURE_NONE | BGFX_SAMPLER_NONE)

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

  Attention

    C99’s equivalent binding is `bgfx_create_texture_2d_scaled`.

  Parameters:

    - _ratio – [in] Frame buffer size in respect to back-buffer size. See: `BackbufferRatio::Enum`.

    - _hasMips – [in] Indicates that texture contains full mip-map chain.

    - _numLayers – [in] Number of layers in texture array. Must be 1 if caps `BGFX_CAPS_TEXTURE_2D_ARRAY` flag is not set.

    - _format – [in] Texture format. See: `TextureFormat::Enum`.

    - _flags – [in] 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.

void bgfx::updateTexture2D(TextureHandle _handle, uint16_t _layer, uint8_t _mip, uint16_t _x, uint16_t _y, uint16_t _width, uint16_t _height, const Memory *_mem, uint16_t _pitch = UINT16_MAX)

  Update 2D texture.

  Attention

    It’s valid to update only mutable texture. See `bgfx::createTexture2D` for more info.

  Attention

    C99’s equivalent binding is `bgfx_update_texture_2d`.

  Parameters:

    - _handle – [in] Texture handle.

    - _layer – [in] Layers in texture array.

    - _mip – [in] Mip level.

    - _x – [in] X offset in texture.

    - _y – [in] Y offset in texture.

    - _width – [in] Width of texture block.

    - _height – [in] Height of texture block.

    - _mem – [in] Texture update data.

    - _pitch – [in] Pitch of input image (bytes). When _pitch is set to UINT16_MAX, it will be calculated internally based on _width.

TextureHandle bgfx::createTexture3D(uint16_t _width, uint16_t _height, uint16_t _depth, bool _hasMips, TextureFormat :: Enum _format, uint64_t _flags = BGFX_TEXTURE_NONE | BGFX_SAMPLER_NONE, const Memory *_mem = NULL)

  Create 3D texture.

  Attention

    C99’s equivalent binding is `bgfx_create_texture_3d`.

  Parameters:

    - _width – [in] Width.

    - _height – [in] Height.

    - _depth – [in] Depth.

    - _hasMips – [in] Indicates that texture contains full mip-map chain.

    - _format – [in] Texture format. See: `TextureFormat::Enum`.

    - _flags – [in] 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.

    - _mem – [in] Texture data. If `_mem` is non-NULL, created texture will be immutable. If `_mem` is NULL content of the texture is uninitialized.

void bgfx::updateTexture3D(TextureHandle _handle, uint8_t _mip, uint16_t _x, uint16_t _y, uint16_t _z, uint16_t _width, uint16_t _height, uint16_t _depth, const Memory *_mem)

  Update 3D texture.

  Attention

    It’s valid to update only mutable texture. See `bgfx::createTexture3D` for more info.

  Attention

    C99’s equivalent binding is `bgfx_update_texture_3d`.

  Parameters:

    - _handle – [in] Texture handle.

    - _mip – [in] Mip level.

    - _x – [in] X offset in texture.

    - _y – [in] Y offset in texture.

    - _z – [in] Z offset in texture.

    - _width – [in] Width of texture block.

    - _height – [in] Height of texture block.

    - _depth – [in] Depth of texture block.

    - _mem – [in] Texture update data.

TextureHandle bgfx::createTextureCube(uint16_t _size, bool _hasMips, uint16_t _numLayers, TextureFormat :: Enum _format, uint64_t _flags = BGFX_TEXTURE_NONE | BGFX_SAMPLER_NONE, const Memory *_mem = NULL)

  Create Cube texture.

  Attention

    C99’s equivalent binding is `bgfx_create_texture_cube`.

  Parameters:

    - _size – [in] Cube side size.

    - _hasMips – [in] Indicates that texture contains full mip-map chain.

    - _numLayers – [in] Number of layers in texture array. Must be 1 if caps `BGFX_CAPS_TEXTURE_CUBE_ARRAY` flag is not set.

    - _format – [in] Texture format. See: `TextureFormat::Enum`.

    - _flags – [in] 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.

    - _mem – [in] Texture data. If `_mem` is non-NULL, created texture will be immutable. If `_mem` is NULL content of the texture is uninitialized. When `_numLayers` is more than 1, expected memory layout is texture and all mips together for each array element.

void bgfx::updateTextureCube(TextureHandle _handle, uint16_t _layer, uint8_t _side, uint8_t _mip, uint16_t _x, uint16_t _y, uint16_t _width, uint16_t _height, const Memory *_mem, uint16_t _pitch = UINT16_MAX)

  Update Cube texture.

  Attention

    It’s valid to update only mutable texture. See `bgfx::createTextureCube` for more info.

  Attention

    C99’s equivalent binding is `bgfx_update_texture_cube`.

  Parameters:

    - _handle – [in] Texture handle.

    - _layer – [in] Layers in texture array.

    - _side – [in] Cubemap side `BGFX_CUBE_MAP_<POSITIVE or NEGATIVE>_<X, Y or Z>`, where 0 is +X, 1 is -X, 2 is +Y, 3 is -Y, 4 is +Z, and 5 is -Z.

                     +----------+
                     |-z       2|
                     | ^  +y    |
                     | |        |    Unfolded cube:
                     | +---->+x |
          +----------+----------+----------+----------+
          |+y       1|+y       4|+y       0|+y       5|
          | ^  -x    | ^  +z    | ^  +x    | ^  -z    |
          | |        | |        | |        | |        |
          | +---->+z | +---->+x | +---->-z | +---->-x |
          +----------+----------+----------+----------+
                     |+z       3|
                     | ^  -y    |
                     | |        |
                     | +---->+x |
                     +----------+

    - _mip – [in] Mip level.

    - _x – [in] X offset in texture.

    - _y – [in] Y offset in texture.

    - _width – [in] Width of texture block.

    - _height – [in] Height of texture block.

    - _mem – [in] Texture update data.

    - _pitch – [in] Pitch of input image (bytes). When _pitch is set to UINT16_MAX, it will be calculated internally based on _width.

uint32_t bgfx::readTexture(TextureHandle _handle, void *_data, uint8_t _mip = 0)

  Read back texture content.

  Attention

    Texture must be created with `BGFX_TEXTURE_READ_BACK` flag.

  Attention

    Availability depends on: `BGFX_CAPS_TEXTURE_READ_BACK`.

  Attention

    C99’s equivalent binding is `bgfx_read_texture`.

  Parameters:

    - _handle – [in] Texture handle.

    - _data – [in] Destination buffer.

    - _mip – [in] Mip level.

  Returns:

    Frame number when the result will be available. See: `bgfx::frame`.

void *bgfx::getDirectAccessPtr(TextureHandle _handle)

  Returns texture direct access pointer.

  Attention

    Availability depends on: `BGFX_CAPS_TEXTURE_DIRECT_ACCESS`. This feature is available on GPUs that have unified memory architecture (UMA) support.

  Attention

    C99’s equivalent binding is `bgfx_get_direct_access_ptr`.

  Parameters:

    _handle – [in] Texture handle.

  Returns:

    Pointer to texture memory. If returned pointer is `NULL` direct access is not available for this texture. If pointer is `UINTPTR_MAX` sentinel value it means texture is pending creation. Pointer returned can be cached and it will be valid until texture is destroyed.

void bgfx::destroy(TextureHandle _handle)

  Destroy texture.

  Attention

    C99’s equivalent binding is `bgfx_destroy_texture`.

  Parameters:

    _handle – [in] Texture handle.

### Frame Buffers

struct Attachment

  Frame buffer texture attachment info.

  Attention

    C99’s equivalent binding is `bgfx_attachment_t`.

  Public Functions

  void init(TextureHandle _handle, Access :: Enum _access = Access :: Write, uint16_t _layer = 0, uint16_t _numLayers = 1, uint16_t _mip = 0, uint8_t _resolve = BGFX_RESOLVE_AUTO_GEN_MIPS)

    Init attachment.

    Parameters:

      - _handle – [in] Render target texture handle.

      - _access – [in] Access. See `Access::Enum`.

      - _layer – [in] Cubemap side or depth layer/slice to use.

      - _numLayers – [in] Number of texture layer/slice(s) in array to use.

      - _mip – [in] Mip level.

      - _resolve – [in] Resolve flags. See: `BGFX_RESOLVE_*`

  Public Members

  Access :: Enum access

    Attachment access. See `Access::Enum`.

  TextureHandle handle

    Render target texture handle.

  uint16_t mip

    Mip level.

  uint16_t layer

    Cubemap side or depth layer/slice to use.

  uint16_t numLayers

    Number of texture layer/slice(s) in array to use.

  uint8_t resolve

    Resolve flags. See: `BGFX_RESOLVE_*`

bool bgfx::isFrameBufferValid(uint8_t _num, const Attachment *_attachment)

  Validate frame buffer parameters.

  Parameters:

    - _num – [in] Number of attachments.

    - _attachment – [in] Attachment texture info. See: `bgfx::Attachment`.

  Returns:

    True if a frame buffer with the same parameters can be created.

FrameBufferHandle bgfx::createFrameBuffer(uint16_t _width, uint16_t _height, TextureFormat :: Enum _format, uint64_t _textureFlags = BGFX_SAMPLER_U_CLAMP | BGFX_SAMPLER_V_CLAMP)

  Create frame buffer (simple).

  Attention

    C99’s equivalent binding is `bgfx_create_frame_buffer`.

  Parameters:

    - _width – [in] Texture width.

    - _height – [in] Texture height.

    - _format – [in] Texture format. See: `TextureFormat::Enum`.

    - _textureFlags – [in] 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.

  Returns:

    Handle to frame buffer object.

FrameBufferHandle bgfx::createFrameBuffer(BackbufferRatio::Enum _ratio, TextureFormat :: Enum _format, uint64_t _textureFlags = BGFX_SAMPLER_U_CLAMP | BGFX_SAMPLER_V_CLAMP)

  Create frame buffer with size based on back-buffer ratio. Frame buffer will maintain ratio if back buffer resolution changes.

  Attention

    C99’s equivalent binding is `bgfx_create_frame_buffer_scaled`.

  Parameters:

    - _ratio – [in] Frame buffer size in respect to back-buffer size. See: `BackbufferRatio::Enum`.

    - _format – [in] Texture format. See: `TextureFormat::Enum`.

    - _textureFlags – [in] 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.

  Returns:

    Handle to frame buffer object.

FrameBufferHandle bgfx::createFrameBuffer(uint8_t _num, const TextureHandle *_handles, bool _destroyTextures = false)

  Create MRT frame buffer from texture handles (simple).

  Attention

    C99’s equivalent binding is `bgfx_create_frame_buffer_from_handles`.

  Parameters:

    - _num – [in] Number of texture attachments.

    - _handles – [in] Texture attachments.

    - _destroyTextures – [in] If true, textures will be destroyed when frame buffer is destroyed.

  Returns:

    Handle to frame buffer object.

FrameBufferHandle bgfx::createFrameBuffer(void *_nwh, uint16_t _width, uint16_t _height, TextureFormat :: Enum _format = TextureFormat :: Count, TextureFormat :: Enum _depthFormat = TextureFormat :: Count )

  Create frame buffer for multiple window rendering.

  Remark

  Frame buffer cannot be used for sampling.

  Attention

    C99’s equivalent binding is `bgfx_create_frame_buffer_from_nwh`.

  Parameters:

    - _nwh – [in] OS’ target native window handle.

    - _width – [in] Window back buffer width.

    - _height – [in] Window back buffer height.

    - _format – [in] Window back buffer color format.

    - _depthFormat – [in] Window back buffer depth format.

  Returns:

    Handle to frame buffer object.

FrameBufferHandle bgfx::createFrameBuffer(uint8_t _num, const Attachment *_attachment, bool _destroyTextures = false)

  Create MRT frame buffer from texture handles with specific layer and mip level.

  Attention

    C99’s equivalent binding is `bgfx_create_frame_buffer_from_attachment`.

  Parameters:

    - _num – [in] Number of texture attachments.

    - _attachment – [in] Attachment texture info. See: `bgfx::Attachment`.

    - _destroyTextures – [in] If true, textures will be destroyed when frame buffer is destroyed.

  Returns:

    Handle to frame buffer object.

TextureHandle bgfx::getTexture(FrameBufferHandle _handle, uint8_t _attachment = 0)

  Obtain texture handle of frame buffer attachment.

  Attention

    C99’s equivalent binding is `bgfx_get_texture`.

  Parameters:

    - _handle – [in] Frame buffer handle.

    - _attachment – [in] Frame buffer attachment index.

  Returns:

    Returns invalid texture handle if attachment index is not correct, or frame buffer is created with native window handle.

void bgfx::setName(FrameBufferHandle _handle, const char *_name, int32_t _len = INT32_MAX)

  Set frame buffer debug name.

  Attention

    C99’s equivalent binding is `bgfx_set_frame_buffer_name`.

  Parameters:

    - _handle – [in] frame buffer handle.

    - _name – [in] frame buffer name.

    - _len – [in] frame buffer name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.

void bgfx::destroy(FrameBufferHandle _handle)

  Destroy frame buffer.

  Attention

    C99’s equivalent binding is `bgfx_destroy_frame_buffer`.

  Parameters:

    _handle – [in] Frame buffer handle.

### Instance Buffer

uint32_t bgfx::getAvailInstanceDataBuffer(uint32_t _num, uint16_t _stride)

  Returns number of requested or maximum available instance buffer slots.

  Attention

    C99’s equivalent binding is `bgfx_get_avail_instance_data_buffer`.

  Parameters:

    - _num – [in] Number of required instances.

    - _stride – [in] Stride per instance.

void bgfx::allocInstanceDataBuffer( InstanceDataBuffer *_idb, uint32_t _num, uint16_t _stride)

  Allocate instance data buffer.

  Attention

    C99’s equivalent binding is `bgfx_alloc_instance_data_buffer`.

  Parameters:

    - _idb – [out] InstanceDataBuffer structure will be filled, and will be valid for the duration of frame, and can be reused for multiple draw calls.

    - _num – [in] Number of instances.

    - _stride – [in] Instance stride. Must be multiple of 16.

### Indirect Buffer

IndirectBufferHandle bgfx::createIndirectBuffer(uint32_t _num)

  Create draw indirect buffer.

  Attention

    C99’s equivalent binding is `bgfx_create_indirect_buffer`.

  Parameters:

    _num – [in] Number of indirect calls.

  Returns:

    Indirect buffer handle.

void bgfx::destroy(IndirectBufferHandle _handle)

  Destroy draw indirect buffer.

  Attention

    C99’s equivalent binding is `bgfx_destroy_indirect_buffer`.

  Parameters:

    _handle – [in] Indirect buffer handle.

### Occlusion Query

OcclusionQueryHandle bgfx::createOcclusionQuery()

  Create occlusion query.

  Attention

    C99’s equivalent binding is `bgfx_create_occlusion_query`.

  Returns:

    Handle to occlusion query object.

struct OcclusionQueryResult

  Occlusion query result.

  Attention

    C99’s equivalent binding is `bgfx_occlusion_query_result_t`.

  Public Types

  enum Enum

    Occlusion query results:

    Values:

    enumerator Invisible

      Query failed test.

    enumerator Visible

      Query passed test.

    enumerator NoResult

      Query result is not available yet.

    enumerator Count

OcclusionQueryResult :: Enum bgfx::getResult(OcclusionQueryHandle _handle, int32_t *_result = NULL)

  Retrieve occlusion query result from previous frame.

  Attention

    C99’s equivalent binding is `bgfx_get_result`.

  Parameters:

    - _handle – [in] Handle to occlusion query object.

    - _result – [out] Number of pixels that passed test. This argument can be `NULL` if result of occlusion query is not needed.

  Returns:

    Occlusion query result.

void bgfx::destroy(OcclusionQueryHandle _handle)

  Destroy occlusion query.

  Attention

    C99’s equivalent binding is `bgfx_destroy_occlusion_query`.

  Parameters:

    _handle – [in] Handle to occlusion query object.