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

General API for initialization, shutdown, frame management, debug, and querying renderer information.

Initialization and Shutdown

BGFX_PCI_ID_NONE

Autoselect adapter.

BGFX_PCI_ID_SOFTWARE_RASTERIZER

Software rasterizer.

BGFX_PCI_ID_AMD

AMD adapter.

BGFX_PCI_ID_APPLE

Apple adapter.

BGFX_PCI_ID_INTEL

Intel adapter.

BGFX_PCI_ID_NVIDIA

nVidia adapter.

BGFX_PCI_ID_MICROSOFT

Microsoft adapter.

BGFX_PCI_ID_ARM

ARM adapter.

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.

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

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

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

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.

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.

void bgfx::shutdown()

Shutdown bgfx library.

Attention

C99’s equivalent binding is bgfx_shutdown.

Updating

Reset

Reset flags control back-buffer resolution, MSAA, vsync, and other global rendering settings.

BGFX_RESET_NONE

No reset flags.

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.

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 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 back-buffer.

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

Frame

Frame flags and the bgfx::frame call to advance to the next frame.

BGFX_FRAME_NONE

No frame flags.

BGFX_FRAME_DEBUG_CAPTURE

Capture frame with graphics debugger.

BGFX_FRAME_DISCARD

Discard all draw calls.

uint32_t bgfx::frame(uint8_t _flags = BGFX_FRAME_NONE)

Advance to next frame. This is the main frame-advancement call on the API thread (the thread from which bgfx::init was called).

Multithreaded renderer (BGFX_CONFIG_MULTITHREADED=1, default): This call waits for the render thread to finish processing the previous frame, then swaps internal submit/render buffers, signals the render thread to begin processing the new frame via bgfx::renderFrame, and returns immediately. The render thread and API thread then run in parallel: the API thread builds the next frame while the render thread executes GPU commands for the current frame.

Single-threaded renderer (BGFX_CONFIG_MULTITHREADED=0, or when bgfx::renderFrame and bgfx::init are called from the same thread): This call swaps internal buffers and performs frame rendering inline (internally calls bgfx::renderFrame), then returns.

Remark

Must be called from the API thread (the thread that called bgfx::init). In multithreaded mode, this call synchronizes with bgfx::renderFrame running on the render thread via semaphores: bgfx::frame waits for the render thread to finish, then posts a signal that bgfx::renderFrame waits on to begin the next frame. See also: bgfx::renderFrame.

Attention

C99’s equivalent binding is bgfx_frame.

Parameters:

_flags – [in] Frame flags. See: BGFX_FRAME_* for more info.

• BGFX_FRAME_NONE - No frame flag.

• BGFX_FRAME_DEBUG_CAPTURE - Capture frame with graphics debugger.

• BGFX_FRAME_DISCARD - Discard all draw calls.

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

Enable or disable 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

Flags for bgfx::setDebug.

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

Functions for printing debug text on screen.

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 formatted data to internal debug text character-buffer (VGA-compatible text mode).

Attention

C99’s equivalent binding is bgfx_dbg_text_printf.

Parameters:

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

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

• _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.

Param :

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

Print formatted data from variable argument list to internal debug text character-buffer (VGA-compatible text mode).

Attention

C99’s equivalent binding is bgfx_dbg_text_vprintf.

Parameters:

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

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

• _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] Variable arguments list 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] Position x from the left corner of the window.

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

• _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

Query the active rendering backend.

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

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.

Returns:

Renderer backend type. See: bgfx::RendererType

Capabilities

Query GPU capabilities and limits.

Available Caps

Individual capability flags.

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_COMPARE_RESERVED

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_EXTERNAL

External texture is supported.

BGFX_CAPS_TEXTURE_EXTERNAL_SHARED

External shared texture is supported.

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.

BGFX_CAPS_TEXTURE_COMPARE_ALL

Statistics

Per-frame rendering statistics.

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.

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.

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.

Returns:

Performance counters.

Platform specific

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

struct RenderFrame

Render frame enum.

Attention

C99’s equivalent binding is bgfx_render_frame_t.

struct InternalData

Internal data.

Attention

C99’s equivalent binding is bgfx_internal_data_t.

Public Members

const Caps *caps

Renderer capabilities.

void *context

GL context, or D3D device.

struct PlatformData

Platform data.

Attention

C99’s equivalent binding is bgfx_platform_data_t.

Public Members

void *ndt

Native display type (*nix specific).

void *nwh

Native window handle. If NULL, bgfx will create a headless context/device, provided the rendering API supports it.

void *context

GL context, D3D device, or Vulkan device. If NULL, bgfx will create context/device.

void *queue

D3D12 Queue. If NULL bgfx will create queue.

void *backBuffer

GL back-buffer, or D3D render target view. If NULL bgfx will create back-buffer color surface.

void *backBufferDS

Backbuffer depth/stencil. If NULL, bgfx will create a back-buffer depth/stencil surface.

NativeWindowHandleType::Enum type

Handle type. Needed for platforms having more than one option.

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

Render frame. Executes the actual GPU rendering work for one frame.

In the default multithreaded configuration, bgfx::renderFrame runs on the render thread while bgfx::frame runs on the API thread. Their interaction is as follows:

1. The render thread calls bgfx::renderFrame, which blocks waiting for the API thread to signal that a new frame is ready.

2. On the API thread, bgfx::frame finishes building the frame, swaps internal submit/render buffers, and signals the render thread.

3. bgfx::renderFrame wakes up, executes pre-render commands, submits GPU draw calls, executes post-render commands, flips the back buffer, then signals back to the API thread that rendering is complete.

4. The API thread’s next bgfx::frame call waits for this completion signal before swapping buffers again.

This double-buffered semaphore handshake allows the API thread and render thread to run in parallel, overlapping CPU frame building with GPU rendering.

Attention

bgfx::renderFrame is a blocking call. It waits for bgfx::frame to be called from the API thread to process the frame. If a timeout value is passed, the call will return RenderFrame::Timeout even if bgfx::frame has not been called. A value of -1 (default) means wait indefinitely (up to BGFX_CONFIG_API_SEMAPHORE_TIMEOUT).

Attention

C99’s equivalent binding is bgfx_render_frame.

Warning

This call should only be used on platforms that don’t allow creating a separate rendering thread. If it is called before bgfx::init, the internal render thread won’t be created by the bgfx::init call, and the user is responsible for calling bgfx::renderFrame on the render thread each frame. If both bgfx::renderFrame and bgfx::init are called from the same thread, bgfx operates in single-threaded mode and bgfx::frame will internally invoke bgfx::renderFrame automatically. See also: bgfx::frame.

Parameters:

_msecs – [in] Timeout in milliseconds.

Returns:

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

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.

Parameters:

_data – [in] Platform data.

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.

Returns:

Internal data.

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] 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:

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

Returns:

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

Miscellaneous

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

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::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 &_dstLayout, void *_dstData, 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:

• _dstLayout – [in] Destination vertex stream layout.

• _dstData – [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. Returns number of unique vertices after welding.

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.

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

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 – [out] 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::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 values.

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

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::setPaletteColor(uint8_t _index, uint32_t _rgba)

Set palette color value.

Attention

C99’s equivalent binding is bgfx_set_palette_color_rgba8.

Parameters:

• _index – [in] Index into palette.

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

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.

void bgfx::touch(ViewId _id)

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

Remark

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::discard(uint8_t _flags = BGFX_DISCARD_ALL)

Discard previously set state for draw or compute call.

Attention

C99’s equivalent binding is bgfx_discard.

Parameters:

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

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.

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

struct ShadingRate

Shading Rate.

Attention

C99’s equivalent binding is bgfx_shading_rate_t.

Public Types

enum Enum

Shading rate:

Values:

enumerator Rate1x1

1x1

enumerator Rate1x2

1x2

enumerator Rate2x1

2x1

enumerator Rate2x2

2x2

enumerator Rate2x4

2x4

enumerator Rate4x2

4x2

enumerator Rate4x4

4x4

enumerator Count

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

Set view name.

In graphics debugger view name will appear as:

"nnnc <view name>"
 ^  ^ ^
 |  +--- 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 view scissor region.

• _height – [in] Height of view 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 _c0 = UINT8_MAX, uint8_t _c1 = UINT8_MAX, uint8_t _c2 = UINT8_MAX, uint8_t _c3 = UINT8_MAX, uint8_t _c4 = UINT8_MAX, uint8_t _c5 = UINT8_MAX, uint8_t _c6 = UINT8_MAX, uint8_t _c7 = 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.

• _c0 – [in] Palette index for frame buffer attachment 0.

• _c1 – [in] Palette index for frame buffer attachment 1.

• _c2 – [in] Palette index for frame buffer attachment 2.

• _c3 – [in] Palette index for frame buffer attachment 3.

• _c4 – [in] Palette index for frame buffer attachment 4.

• _c5 – [in] Palette index for frame buffer attachment 5.

• _c6 – [in] Palette index for frame buffer attachment 6.

• _c7 – [in] Palette index for frame buffer attachment 7.

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

• _order – [in] View remap id table. Passing NULL will reset view ids to default state.

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] _id View id.

Encoder

Encoder

API for multi-threaded submission.

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

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.

Remark

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 corner of the window.

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

• _width – [in] Width of view scissor region.

• _height – [in] Height of view scissor region.

Returns:

Scissor cache index.

void setScissor(uint16_t _cache = UINT16_MAX)

Set scissor from cache for draw primitive.

Remark

To scissor for all primitives in view see bgfx::setViewScissor.

Attention

C99’s equivalent binding is bgfx_encoder_set_scissor_cached.

Parameters:

_cache – [in] Index in scissor cache.

uint32_t 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_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.

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.

uint32_t allocTransform(Transform *_transform, uint16_t _num)

Reserve 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 – [out] Pointer to Transform structure.

• _num – [in] Number of matrices.

Returns:

Index in matrix 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.

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.

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.

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.

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 bindings are bgfx_encoder_set_vertex_buffer_with_layout, 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.

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 bindings are bgfx_encoder_set_dynamic_vertex_buffer_with_layout, 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.

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 bindings are bgfx_encoder_set_transient_vertex_buffer_with_layout, 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.

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 _startVertex, 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.

• _startVertex – [in] First instance data.

• _num – [in] Number of data instances.

void setInstanceDataBuffer(DynamicVertexBufferHandle _handle, uint32_t _startVertex, 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] Dynamic vertex buffer.

• _startVertex – [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.

Remark

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] Compute stage.

• _handle – [in] Texture handle.

• _mip – [in] Mip level.

• _access – [in] Image access. See Access::Enum.

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

void dispatch(ViewId _id, ProgramHandle _program, 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.

• _program – [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 _program, 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.

• _program – [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 previously set state for draw or compute call.

Attention

C99’s equivalent binding is bgfx_encoder_discard.

Parameters:

_flags – [in] Discard or preserve states. See BGFX_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 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.

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

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

Begin submitting draw calls from thread.

Attention

C99’s equivalent binding is bgfx_encoder_begin.

Parameters:

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

Returns:

Encoder.

void bgfx::end(Encoder *_encoder)

End submitting draw calls from thread.

Attention

C99’s equivalent binding is bgfx_encoder_end.

Parameters:

_encoder – [in] Encoder.

Draw

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

Debug

Debug markers for grouping draw calls in graphics debugging tools.

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.

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.

State

Configure render state for draw calls.

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

State Flags

Render state flags for depth test, blending, culling, etc.

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_A

Enable alpha write.

BGFX_STATE_WRITE_Z

Enable depth write. Enable RGB write.

BGFX_STATE_WRITE_RGB

BGFX_STATE_WRITE_MASK

Write all channels mask.

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

BGFX_STATE_CONSERVATIVE_RASTER

Enable conservative rasterization.

BGFX_STATE_NONE

No state.

BGFX_STATE_FRONT_CCW

Front counter-clockwise (default is clockwise).

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_DEFAULT

Stencil

Configure stencil test for draw calls.

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

Stencil test configuration flags.

BGFX_STENCIL_TEST_LESS

Enable stencil test, less.

BGFX_STENCIL_TEST_LEQUAL

Enable stencil test, less or equal.

BGFX_STENCIL_TEST_EQUAL

Enable stencil test, equal.

BGFX_STENCIL_TEST_GEQUAL

Enable stencil test, greater or equal.

BGFX_STENCIL_TEST_GREATER

Enable stencil test, greater.

BGFX_STENCIL_TEST_NOTEQUAL

Enable stencil test, not equal.

BGFX_STENCIL_TEST_NEVER

Enable stencil test, never.

BGFX_STENCIL_TEST_ALWAYS

Enable stencil test, always.

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.

Remark

To 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 view scissor region.

• _height – [in] Height of view scissor region.

Returns:

Scissor cache index.

void bgfx::setScissor(uint16_t _cache = UINT16_MAX)

Set scissor from cache for draw primitive.

Remark

To scissor for all primitives in view see bgfx::setViewScissor.

Attention

C99’s equivalent binding is bgfx_set_scissor_cached.

Parameters:

_cache – [in] Index in scissor cache.

Transform

Set model transform matrices for draw calls.

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.

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

Reserve 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 – [out] Pointer to Transform structure.

• _num – [in] Number of matrices.

Returns:

Index in matrix cache.

Conditional Rendering

Conditionally render based on occlusion query results.

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

Set vertex, index, and instance data buffers for draw calls.

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.

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.

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::setIndexBuffer(IndexBufferHandle _handle)

Set index buffer for draw primitive.

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.

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.

void bgfx::setIndexBuffer(const TransientIndexBuffer *_tib)

Set index buffer for draw primitive.

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, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)

Set vertex buffer for draw primitive.

Attention

C99’s equivalent bindings are bgfx_set_vertex_buffer_with_layout, 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, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)

Set vertex buffer for draw primitive.

Attention

C99’s equivalent bindings are bgfx_set_dynamic_vertex_buffer_with_layout, 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.

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 bindings are bgfx_set_transient_vertex_buffer_with_layout, 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.

void bgfx::setInstanceDataBuffer(const InstanceDataBuffer *_idb)

Set instance data buffer for draw primitive.

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 _startVertex, 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.

• _startVertex – [in] First instance data.

• _num – [in] Number of data instances.

void bgfx::setInstanceDataBuffer(DynamicVertexBufferHandle _handle, uint32_t _startVertex, 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] Dynamic vertex buffer.

• _startVertex – [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

Bind textures to texture stages for draw calls.

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

Set shader uniform parameters for draw calls.

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.

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.

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] Which states to discard for next draw. 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] Which states to discard for next draw. 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] Which states to discard for next draw. 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] Which states to discard for next draw. See BGFX_DISCARD_*.

Compute

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

Buffers

Bind buffers to compute stages.

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

Bind texture images to compute stages.

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] Compute stage.

• _handle – [in] Texture handle.

• _mip – [in] Mip level.

• _access – [in] Image 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 _program, 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.

• _program – [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 _program, 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.

• _program – [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.

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

• _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

Shaders and Programs

Note

Shaders must be compiled with offline command line tool 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.

Parameters:

_mem – [in] Shader binary.

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

Remark

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 _destroyShaders = false)

Create program with compute shader.

Attention

C99’s equivalent binding is bgfx_create_compute_program.

Parameters:

• _csh – [in] Compute shader.

• _destroyShaders – [in] If true, shaders 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

struct UniformFreq

Uniform frequency enum.

Attention

C99’s equivalent binding is 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

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.

UniformHandle bgfx::createUniform(const char *_name, 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.

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.

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.

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

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

struct VertexLayout

Vertex layout.

Attention

C99’s equivalent binding is bgfx_vertex_layout_t.

Public Functions

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

Start VertexLayout.

Attention

C99’s equivalent binding is bgfx_vertex_layout_begin.

Parameters:

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

Returns:

Returns itself.

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.

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.

Parameters:

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

• _num – [out] Number of elements.

• _type – [out] Element type.

• _normalized – [out] Attribute is normalized.

• _asInt – [out] Attribute is packed as int.

inline bool has(Attrib::Enum _attrib) const

Returns true if VertexLayout contains attribute.

Parameters:

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

Returns:

True if VertexLayout contains attribute.

VertexLayout &skip(uint8_t _num)

Skip _num bytes in vertex stream.

Attention

C99’s equivalent binding is bgfx_vertex_layout_skip.

Parameters:

_num – [in] Number of bytes to skip.

Returns:

Returns itself.

void end()

End VertexLayout.

Attention

C99’s equivalent binding is bgfx_vertex_layout_end.

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.

VertexLayoutHandle bgfx::createVertexLayout(const VertexLayout &_layout)

Create vertex layout. Vertex layouts are used to describe the format of vertex data.

Attention

C99’s equivalent binding is bgfx_create_vertex_layout.

Parameters:

_layout – [in] Vertex layout.

void bgfx::destroy(VertexLayoutHandle _layoutHandle)

Destroy vertex layout.

Attention

C99’s equivalent binding is bgfx_destroy_vertex_layout.

Parameters:

_layoutHandle – [in] Vertex layout handle.

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.

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.

Returns:

Number of requested or maximum available vertices.

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.

Returns:

Number of requested or maximum available indices.

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

BGFX_TEXTURE_NONE

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_EXTERNAL_SHARED

Texture is shared with other device or other process.

BGFX_TEXTURE_RT_WRITE_ONLY

Render target will be used for writing.

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

Block Compression 1. 5-bit R, 6-bit G, 5-bit B, 1-bit A. 4 BPP.

enumerator BC2

Block Compression 2. 5-bit R, 6-bit G, 5-bit B, 4-bit explicit A. 8 BPP.

enumerator BC3

Block Compression 3. 5-bit R, 6-bit G, 5-bit B, 8-bit interpolated A. 8 BPP.

enumerator BC4

Block Compression 4. Single 8-bit red channel, unsigned normalized. 4 BPP.

enumerator BC5

Block Compression 5. Two 8-bit channels (RG), unsigned normalized. 8 BPP.

enumerator BC6H

Block Compression 6H. Three 16-bit floating-point channels (RGB), HDR. 8 BPP.

enumerator BC7

RGB 4-7 bits per color channel, 0-8 bits alpha. Block Compression 7. High-quality RGBA, 4-7 bits per color, 0-8 bits alpha. 8 BPP.

enumerator ETC1

Ericsson Texture Compression 1. 8-bit per channel RGB. 4 BPP.

enumerator ETC2

Ericsson Texture Compression 2. 8-bit per channel RGB. 4 BPP.

enumerator ETC2A

Ericsson Texture Compression 2 with full alpha. 8-bit per channel RGBA. 8 BPP.

enumerator ETC2A1

Ericsson Texture Compression 2 with 1-bit punch-through alpha. 4 BPP.

enumerator EACR11

ETC2 Alpha Compression, single 11-bit red channel, unsigned normalized. 4 BPP.

enumerator EACR11S

ETC2 Alpha Compression, single 11-bit red channel, signed normalized. 4 BPP.

enumerator EACRG11

ETC2 Alpha Compression, two 11-bit channels (RG), unsigned normalized. 8 BPP.

enumerator EACRG11S

ETC2 Alpha Compression, two 11-bit channels (RG), signed normalized. 8 BPP.

enumerator PTC12

PowerVR Texture Compression v1. 3-channel RGB. 2 BPP.

enumerator PTC14

PowerVR Texture Compression v1. 3-channel RGB. 4 BPP.

enumerator PTC12A

PowerVR Texture Compression v1. 4-channel RGBA. 2 BPP.

enumerator PTC14A

PowerVR Texture Compression v1. 4-channel RGBA. 4 BPP.

enumerator PTC22

PowerVR Texture Compression v2. 4-channel RGBA. 2 BPP.

enumerator PTC24

PowerVR Texture Compression v2. 4-channel RGBA. 4 BPP.

enumerator ATC

AMD Texture Compression. 3-channel RGB. 4 BPP.

enumerator ATCE

AMD Texture Compression with explicit alpha. 4-channel RGBA. 8 BPP.

enumerator ATCI

AMD Texture Compression with interpolated alpha. 4-channel RGBA. 8 BPP.

enumerator ASTC4x4

Adaptive Scalable Texture Compression, 4x4 block, RGBA. 8.00 BPP.

enumerator ASTC5x4

Adaptive Scalable Texture Compression, 5x4 block, RGBA. 6.40 BPP.

enumerator ASTC5x5

Adaptive Scalable Texture Compression, 5x5 block, RGBA. 5.12 BPP.

enumerator ASTC6x5

Adaptive Scalable Texture Compression, 6x5 block, RGBA. 4.27 BPP.

enumerator ASTC6x6

Adaptive Scalable Texture Compression, 6x6 block, RGBA. 3.56 BPP.

enumerator ASTC8x5

Adaptive Scalable Texture Compression, 8x5 block, RGBA. 3.20 BPP.

enumerator ASTC8x6

Adaptive Scalable Texture Compression, 8x6 block, RGBA. 2.67 BPP.

enumerator ASTC8x8

Adaptive Scalable Texture Compression, 8x8 block, RGBA. 2.00 BPP.

enumerator ASTC10x5

Adaptive Scalable Texture Compression, 10x5 block, RGBA. 2.56 BPP.

enumerator ASTC10x6

Adaptive Scalable Texture Compression, 10x6 block, RGBA. 2.13 BPP.

enumerator ASTC10x8

Adaptive Scalable Texture Compression, 10x8 block, RGBA. 1.60 BPP.

enumerator ASTC10x10

Adaptive Scalable Texture Compression, 10x10 block, RGBA. 1.28 BPP.

enumerator ASTC12x10

Adaptive Scalable Texture Compression, 12x10 block, RGBA. 1.07 BPP.

enumerator ASTC12x12

Adaptive Scalable Texture Compression, 12x12 block, RGBA. 0.89 BPP.

enumerator Unknown

Compressed formats above.

enumerator R1

1-bit single-channel red. Monochrome, 1-bit per pixel. 1 BPP.

enumerator A8

8-bit single-channel alpha, unsigned normalized. 8 BPP.

enumerator R8

8-bit single-channel red, unsigned normalized. 8 BPP.

enumerator R8I

8-bit single-channel red, signed integer. 8 BPP.

enumerator R8U

8-bit single-channel red, unsigned integer. 8 BPP.

enumerator R8S

8-bit single-channel red, signed normalized. 8 BPP.

enumerator R16

16-bit single-channel red, unsigned normalized. 16 BPP.

enumerator R16I

16-bit single-channel red, signed integer. 16 BPP.

enumerator R16U

16-bit single-channel red, unsigned integer. 16 BPP.

enumerator R16F

16-bit single-channel red, half-precision floating point. 16 BPP.

enumerator R16S

16-bit single-channel red, signed normalized. 16 BPP.

enumerator R32I

32-bit single-channel red, signed integer. 32 BPP.

enumerator R32U

32-bit single-channel red, unsigned integer. 32 BPP.

enumerator R32F

32-bit single-channel red, full-precision floating point. 32 BPP.

enumerator RG8

Two 8-bit channels (red, green), unsigned normalized. 16 BPP.

enumerator RG8I

Two 8-bit channels (red, green), signed integer. 16 BPP.

enumerator RG8U

Two 8-bit channels (red, green), unsigned integer. 16 BPP.

enumerator RG8S

Two 8-bit channels (red, green), signed normalized. 16 BPP.

enumerator RG16

Two 16-bit channels (red, green), unsigned normalized. 32 BPP.

enumerator RG16I

Two 16-bit channels (red, green), signed integer. 32 BPP.

enumerator RG16U

Two 16-bit channels (red, green), unsigned integer. 32 BPP.

enumerator RG16F

Two 16-bit channels (red, green), half-precision floating point. 32 BPP.

enumerator RG16S

Two 16-bit channels (red, green), signed normalized. 32 BPP.

enumerator RG32I

Two 32-bit channels (red, green), signed integer. 64 BPP.

enumerator RG32U

Two 32-bit channels (red, green), unsigned integer. 64 BPP.

enumerator RG32F

Two 32-bit channels (red, green), full-precision floating point. 64 BPP.

enumerator RGB8

Three 8-bit channels (red, green, blue), unsigned normalized. 24 BPP.

enumerator RGB8I

Three 8-bit channels (red, green, blue), signed integer. 24 BPP.

enumerator RGB8U

Three 8-bit channels (red, green, blue), unsigned integer. 24 BPP.

enumerator RGB8S

Three 8-bit channels (red, green, blue), signed normalized. 24 BPP.

enumerator RGB9E5F

Shared-exponent RGB. 9 bits per RGB channel with a shared 5-bit exponent, floating point. 32 BPP.

enumerator BGRA8

Four 8-bit channels (blue, green, red, alpha), unsigned normalized. BGRA byte order. 32 BPP.

enumerator RGBA8

Four 8-bit channels (red, green, blue, alpha), unsigned normalized. 32 BPP.

enumerator RGBA8I

Four 8-bit channels (red, green, blue, alpha), signed integer. 32 BPP.

enumerator RGBA8U

Four 8-bit channels (red, green, blue, alpha), unsigned integer. 32 BPP.

enumerator RGBA8S

Four 8-bit channels (red, green, blue, alpha), signed normalized. 32 BPP.

enumerator RGBA16

Four 16-bit channels (red, green, blue, alpha), unsigned normalized. 64 BPP.

enumerator RGBA16I

Four 16-bit channels (red, green, blue, alpha), signed integer. 64 BPP.

enumerator RGBA16U

Four 16-bit channels (red, green, blue, alpha), unsigned integer. 64 BPP.

enumerator RGBA16F

Four 16-bit channels (red, green, blue, alpha), half-precision floating point. 64 BPP.

enumerator RGBA16S

Four 16-bit channels (red, green, blue, alpha), signed normalized. 64 BPP.

enumerator RGBA32I

Four 32-bit channels (red, green, blue, alpha), signed integer. 128 BPP.

enumerator RGBA32U

Four 32-bit channels (red, green, blue, alpha), unsigned integer. 128 BPP.

enumerator RGBA32F

Four 32-bit channels (red, green, blue, alpha), full-precision floating point. 128 BPP.

enumerator B5G6R5

Packed 16-bit, 5-bit blue, 6-bit green, 5-bit red. BGR byte order, unsigned normalized. 16 BPP.

enumerator R5G6B5

Packed 16-bit, 5-bit red, 6-bit green, 5-bit blue. RGB byte order, unsigned normalized. 16 BPP.

enumerator BGRA4

Packed 16-bit, 4-bit per channel (blue, green, red, alpha). BGRA byte order, unsigned normalized. 16 BPP.

enumerator RGBA4

Packed 16-bit, 4-bit per channel (red, green, blue, alpha), unsigned normalized. 16 BPP.

enumerator BGR5A1

Packed 16-bit, 5-bit blue, 5-bit green, 5-bit red, 1-bit alpha. BGRA byte order, unsigned normalized. 16 BPP.

enumerator RGB5A1

Packed 16-bit, 5-bit red, 5-bit green, 5-bit blue, 1-bit alpha, unsigned normalized. 16 BPP.

enumerator RGB10A2

Packed 32-bit, 10-bit red, 10-bit green, 10-bit blue, 2-bit alpha, unsigned normalized. 32 BPP.

enumerator RG11B10F

Packed 32-bit, 11-bit red, 11-bit green, 10-bit blue, unsigned floating point. No alpha. 32 BPP.

enumerator UnknownDepth

Depth formats below.

enumerator D16

16-bit depth, unsigned normalized. 16 BPP.

enumerator D24

24-bit depth, unsigned normalized (stored as 32-bit with 8 bits unused). 32 BPP.

enumerator D24S8

24-bit depth, unsigned normalized, with 8-bit stencil. 32 BPP.

enumerator D32

32-bit depth, unsigned normalized. 32 BPP.

enumerator D16F

16-bit depth, floating point. 16 BPP.

enumerator D24F

24-bit depth, floating point (stored as 32-bit). 32 BPP.

enumerator D32F

32-bit depth, floating point. 32 BPP.

enumerator D0S8

8-bit stencil only, no depth. 8 BPP.

enumerator Count

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.

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.

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 binary 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, uint64_t _external = 0)

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.

• _external – [in] Native API pointer to texture.

Returns:

Texture handle.

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] Texture 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.

Returns:

Texture handle.

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, uint64_t _external = 0)

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. When _numLayers is more than 1, expected memory layout is texture and all mips together for each array element.

• _external – [in] Native API pointer to texture.

Returns:

Texture handle.

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, uint64_t _external = 0)

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_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

• _external – [in] Native API pointer to texture.

Returns:

Texture handle.

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] Layer 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.

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.

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] Layer 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.

Attention

C99’s equivalent binding is bgfx_attachment_init.

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.

Attention

C99’s equivalent binding is bgfx_is_frame_buffer_valid.

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:

Frame buffer handle.

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:

Frame buffer handle.

FrameBufferHandle bgfx::createFrameBuffer(uint8_t _num, const TextureHandle *_handles, bool _destroyTexture = 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 handles.

• _handles – [in] Texture attachments.

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

Returns:

Frame buffer handle.

FrameBufferHandle bgfx::createFrameBuffer(uint8_t _num, const Attachment *_attachment, bool _destroyTexture = 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 attachments.

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

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

Returns:

Frame buffer handle.

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

Availability depends on: BGFX_CAPS_SWAP_CHAIN.

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:

Frame buffer 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.

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 –

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.

Returns:

Number of requested or maximum available instance buffer slots.

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

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

OcclusionQueryHandle bgfx::createOcclusionQuery()

Create occlusion query. Occlusion queries allow the GPU to determine if any pixels passed the depth test.

Attention

C99’s equivalent binding is bgfx_create_occlusion_query.

Returns:

Handle to occlusion query object.

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.