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!

• bgfx-minimal-example

• Using the bgfx library with C++ on Ubuntu

General

Initialization and Shutdown

struct Init

Initialization parameters used by bgfx::init.

Attention

C99’s equivalent binding is bgfx_init_t.

Public Members

RendererType::Enum type

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

uint16_t vendorId

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

• BGFX_PCI_ID_NONE - Auto-select adapter.

• BGFX_PCI_ID_SOFTWARE_RASTERIZER - Software rasterizer.

• BGFX_PCI_ID_AMD - AMD adapter.

• BGFX_PCI_ID_APPLE - Apple adapter.

• BGFX_PCI_ID_INTEL - Intel adapter.

• BGFX_PCI_ID_NVIDIA - NVIDIA adapter.

• BGFX_PCI_ID_MICROSOFT - Microsoft adapter.

uint16_t deviceId

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

uint64_t capabilities

Capabilities initialization mask (default: UINT64_MAX).

bool debug

Enable device for debugging.

bool profile

Enable device for profiling.

PlatformData platformData

Platform data.

Resolution resolution

Backbuffer resolution and reset parameters. See: bgfx::Resolution.

Limits limits

Configurable runtime limits.

CallbackI *callback

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

bx::AllocatorI *allocator

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

struct Limits

Configurable runtime limits parameters.

Attention

C99’s equivalent binding is bgfx_init_limits_t.

Public Members

uint16_t maxEncoders

Maximum number of encoder threads.

uint32_t minResourceCbSize

Minimum resource command buffer size.

uint32_t maxTransientVbSize

Maximum transient vertex buffer size.

uint32_t maxTransientIbSize

Maximum transient index buffer size.

uint32_t minUniformBufferSize

Mimimum uniform buffer size.

struct Resolution

Backbuffer resolution and reset parameters.

Attention

C99’s equivalent binding is bgfx_resolution_t.

Public Members

TextureFormat::Enum formatColor

Backbuffer color format.

TextureFormat::Enum formatDepthStencil

Backbuffer depth/stencil format.

uint32_t width

Backbuffer width.

uint32_t height

Backbuffer height.

uint32_t reset

Reset parameters.

uint8_t numBackBuffers

Number of back buffers.

uint8_t maxFrameLatency

Maximum frame latency.

uint8_t debugTextScale

Scale factor for debug text.

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

Initialize the bgfx library.

Attention

C99’s equivalent binding is bgfx_init.

Parameters:

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

Returns:

true if initialization was successful.

BGFX_PCI_ID_NONE

Autoselect adapter.

BGFX_PCI_ID_SOFTWARE_RASTERIZER

Software rasterizer.

BGFX_PCI_ID_AMD

AMD adapter.

BGFX_PCI_ID_APPLE

Apple adapter.

BGFX_PCI_ID_INTEL

Intel adapter.

BGFX_PCI_ID_NVIDIA

nVidia adapter.

BGFX_PCI_ID_MICROSOFT

Microsoft adapter.

struct CallbackI

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

Remark

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

Attention

C99’s equivalent binding is bgfx_callback_interface_t.

Public Functions

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

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

Remark

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

Attention

C99’s equivalent binding is bgfx_callback_vtbl.fatal.

Parameters:

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

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

• _code – [in] Fatal error code.

• _str – [in] More information about error.

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

Print debug message.

Remark

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

Attention

C99’s equivalent binding is bgfx_callback_vtbl.trace_vargs.

Parameters:

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

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

• _format – [in] printf style format.

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

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

Profiler region begin.

Remark

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

Attention

C99’s equivalent binding is bgfx_callback_vtbl.profiler_begin.

Parameters:

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

• _abgr – [in] Color of profiler region.

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

• _line – [in] Line where profilerBegin was called.

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

Profiler region begin with string literal name.

Remark

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

Attention

C99’s equivalent binding is bgfx_callback_vtbl.profiler_begin_literal.

Parameters:

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

• _abgr – [in] Color of profiler region.

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

• _line – [in] Line where profilerBeginLiteral was called.

virtual void profilerEnd() = 0

Profiler region end.

Remark

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

Attention

C99’s equivalent binding is bgfx_callback_vtbl.profiler_end.

virtual uint32_t cacheReadSize(uint64_t _id) = 0

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

Attention

C99’s equivalent binding is bgfx_callback_vtbl.cache_read_size.

Parameters:

_id – [in] Cache id.

Returns:

Number of bytes to read.

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

Read cached item.

Attention

C99’s equivalent binding is bgfx_callback_vtbl.cache_read.

Parameters:

• _id – [in] Cache id.

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

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

Returns:

True if data is read.

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

Write cached item.

Attention

C99’s equivalent binding is bgfx_callback_vtbl.cache_write.

Parameters:

• _id – [in] Cache id.

• _data – [in] Data to write.

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

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

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

Attention

C99’s equivalent binding is bgfx_callback_vtbl.screen_shot.

Parameters:

• _filePath – [in] File path.

• _width – [in] Image width.

• _height – [in] Image height.

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

• _data – [in] Image data.

• _size – [in] Image size.

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

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

Called when a video capture begins.

Attention

C99’s equivalent binding is bgfx_callback_vtbl.capture_begin.

Parameters:

• _width – [in] Image width.

• _height – [in] Image height.

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

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

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

virtual void captureEnd() = 0

Called when a video capture ends.

Attention

C99’s equivalent binding is bgfx_callback_vtbl.capture_end.

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

Captured frame.

Attention

C99’s equivalent binding is bgfx_callback_vtbl.capture_frame.

Parameters:

• _data – [in] Image data.

• _size – [in] Image size.

void bgfx::shutdown()

Shutdown bgfx library.

Attention

C99’s equivalent binding is bgfx_shutdown.

Updating

Reset

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

Reset graphic settings and back-buffer size.

Attention

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

Attention

C99’s equivalent binding is bgfx_reset.

Parameters:

• _width – [in] Back-buffer width.

• _height – [in] Back-buffer height.

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

  • BGFX_RESET_NONE - No reset flags.

  • BGFX_RESET_FULLSCREEN - Not supported yet.

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

  • BGFX_RESET_VSYNC - Enable V-Sync.

  • BGFX_RESET_MAXANISOTROPY - Turn on/off max anisotropy.

  • BGFX_RESET_CAPTURE - Begin screen capture.

  • BGFX_RESET_FLUSH_AFTER_RENDER - Flush rendering after submitting to GPU.

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

  • BGFX_RESET_SRGB_BACKBUFFER - Enable sRGB back-buffer.

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

BGFX_RESET_NONE

No reset flags.

BGFX_RESET_MSAA_X2

Enable 2x MSAA.

BGFX_RESET_MSAA_X4

Enable 4x MSAA.

BGFX_RESET_MSAA_X8

Enable 8x MSAA.

BGFX_RESET_MSAA_X16

Enable 16x MSAA.

BGFX_RESET_FULLSCREEN

Not supported yet.

BGFX_RESET_VSYNC

Enable V-Sync.

BGFX_RESET_MAXANISOTROPY

Turn on/off max anisotropy.

BGFX_RESET_CAPTURE

Begin screen capture.

BGFX_RESET_FLUSH_AFTER_RENDER

Flush rendering after submitting to GPU.

BGFX_RESET_FLIP_AFTER_RENDER

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

BGFX_RESET_SRGB_BACKBUFFER

Enable sRGB backbuffer.

BGFX_RESET_HDR10

Enable HDR10 rendering.

BGFX_RESET_HIDPI

Enable HiDPI rendering.

BGFX_RESET_DEPTH_CLAMP

Enable depth clamp.

BGFX_RESET_SUSPEND

Suspend rendering.

BGFX_RESET_TRANSPARENT_BACKBUFFER

Transparent backbuffer. Availability depends on: BGFX_CAPS_TRANSPARENT_BACKBUFFER.

Frame

uint32_t bgfx::frame(bool _capture = false)

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

Attention

C99’s equivalent binding is bgfx_frame.

Parameters:

_capture – [in] Capture frame with graphics debugger.

Returns:

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

Debug

Debug Features

void bgfx::setDebug(uint32_t _debug)

Set debug flags.

Attention

C99’s equivalent binding is bgfx_set_debug.

Parameters:

_debug – [in] Available flags:

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

• BGFX_DEBUG_PROFILER - Enable profiler.

• BGFX_DEBUG_STATS - Display internal statistics.

• BGFX_DEBUG_TEXT - Display debug text.

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

Debug Flags

BGFX_DEBUG_NONE

No debug.

BGFX_DEBUG_WIREFRAME

Enable wireframe for all primitives.

BGFX_DEBUG_IFH

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

BGFX_DEBUG_STATS

Enable statistics display.

BGFX_DEBUG_TEXT

Enable debug text display.

BGFX_DEBUG_PROFILER

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

Debug Text Display

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

Clear internal debug text buffer.

Attention

C99’s equivalent binding is bgfx_dbg_text_clear.

Parameters:

• _attr – [in] Background color.

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

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

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

Attention

C99’s equivalent binding is bgfx_dbg_text_printf.

Parameters:

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

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

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

• _format – [in] printf style format.

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

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

Attention

C99’s equivalent binding is bgfx_dbg_text_vprintf.

Parameters:

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

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

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

• _format – [in] printf style format.

• _argList – [in] additional arguments for format string

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

Draw image into internal debug text buffer.

Attention

C99’s equivalent binding is bgfx_dbg_text_image.

Parameters:

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

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

• _width – [in] Image width

• _height – [in] Image height

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

• _pitch – [in] Image pitch in bytes.

Querying information

Renderer

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

Returns supported backend API renderers.

Attention

C99’s equivalent binding is bgfx_get_supported_renderers.

Parameters:

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

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

Returns:

Number of supported renderers.

RendererType::Enum bgfx::getRendererType()

Returns current renderer backend API type.

Remark

Library must be initialized.

Attention

C99’s equivalent binding is bgfx_get_renderer_type.

struct RendererType

Renderer backend type enum.

Attention

C99’s equivalent binding is bgfx_renderer_type_t.

Public Types

enum Enum

Renderer types:

Values:

enumerator Noop

No rendering.

enumerator Agc

AGC.

enumerator Direct3D11

Direct3D 11.0.

enumerator Direct3D12

Direct3D 12.0.

enumerator Gnm

GNM.

enumerator Metal

Metal.

enumerator Nvn

NVN.

enumerator OpenGLES

OpenGL ES 2.0+.

enumerator OpenGL

OpenGL 2.1+.

enumerator Vulkan

Vulkan.

enumerator Count

Capabilities

const Caps *bgfx::getCaps()

Returns renderer capabilities.

Remark

Library must be initialized.

Attention

C99’s equivalent binding is bgfx_get_caps.

Returns:

Pointer to static bgfx::Caps structure.

struct Caps

Renderer capabilities.

Attention

C99’s equivalent binding is bgfx_caps_t.

Public Members

RendererType::Enum rendererType

Renderer backend type. See: bgfx::RendererType

uint64_t supported

Supported functionality.

Attention

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

uint16_t vendorId

Selected GPU vendor PCI id.

uint16_t deviceId

Selected GPU device id.

bool homogeneousDepth

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

bool originBottomLeft

True when NDC origin is at bottom left.

uint8_t numGPUs

Number of enumerated GPUs.

GPU gpu[4]

Enumerated GPUs.

Limits limits

Renderer runtime limits.

uint16_t formats[TextureFormat::Count]

Supported texture format capabilities flags:

• BGFX_CAPS_FORMAT_TEXTURE_NONE - Texture format is not supported.

• BGFX_CAPS_FORMAT_TEXTURE_2D - Texture format is supported.

• BGFX_CAPS_FORMAT_TEXTURE_2D_SRGB - Texture as sRGB format is supported.

• BGFX_CAPS_FORMAT_TEXTURE_2D_EMULATED - Texture format is emulated.

• BGFX_CAPS_FORMAT_TEXTURE_3D - Texture format is supported.

• BGFX_CAPS_FORMAT_TEXTURE_3D_SRGB - Texture as sRGB format is supported.

• BGFX_CAPS_FORMAT_TEXTURE_3D_EMULATED - Texture format is emulated.

• BGFX_CAPS_FORMAT_TEXTURE_CUBE - Texture format is supported.

• BGFX_CAPS_FORMAT_TEXTURE_CUBE_SRGB - Texture as sRGB format is supported.

• BGFX_CAPS_FORMAT_TEXTURE_CUBE_EMULATED - Texture format is emulated.

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

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

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

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

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

• BGFX_CAPS_FORMAT_TEXTURE_MSAA - Texture can be sampled as MSAA.

• BGFX_CAPS_FORMAT_TEXTURE_MIP_AUTOGEN - Texture format supports auto-generated mips.

struct GPU

GPU info.

Attention

C99’s equivalent binding is bgfx_caps_gpu_t.

Public Members

uint16_t vendorId

Vendor PCI id. See BGFX_PCI_ID_*.

uint16_t deviceId

Device id.

struct Limits

Renderer runtime limits.

Attention

C99’s equivalent binding is bgfx_caps_limits_t.

Public Members

uint32_t maxDrawCalls

Maximum number of draw calls.

uint32_t maxBlits

Maximum number of blit calls.

uint32_t maxTextureSize

Maximum texture size.

uint32_t maxTextureLayers

Maximum texture layers.

uint32_t maxViews

Maximum number of views.

uint32_t maxFrameBuffers

Maximum number of frame buffer handles.

uint32_t maxFBAttachments

Maximum number of frame buffer attachments.

uint32_t maxPrograms

Maximum number of program handles.

uint32_t maxShaders

Maximum number of shader handles.

uint32_t maxTextures

Maximum number of texture handles.

uint32_t maxTextureSamplers

Maximum number of texture samplers.

uint32_t maxComputeBindings

Maximum number of compute bindings.

uint32_t maxVertexLayouts

Maximum number of vertex format layouts.

uint32_t maxVertexStreams

Maximum number of vertex streams.

uint32_t maxIndexBuffers

Maximum number of index buffer handles.

uint32_t maxVertexBuffers

Maximum number of vertex buffer handles.

uint32_t maxDynamicIndexBuffers

Maximum number of dynamic index buffer handles.

uint32_t maxDynamicVertexBuffers

Maximum number of dynamic vertex buffer handles.

uint32_t maxUniforms

Maximum number of uniform handles.

uint32_t maxOcclusionQueries

Maximum number of occlusion query handles.

uint32_t maxEncoders

Maximum number of encoder threads.

uint32_t minResourceCbSize

Minimum resource command buffer size.

uint32_t maxTransientVbSize

Maximum transient vertex buffer size.

uint32_t maxTransientIbSize

Maximum transient index buffer size.

uint32_t minUniformBufferSize

Mimimum uniform buffer size.

Available Caps

BGFX_CAPS_ALPHA_TO_COVERAGE

Alpha to coverage is supported.

BGFX_CAPS_BLEND_INDEPENDENT

Blend independent is supported.

BGFX_CAPS_COMPUTE

Compute shaders are supported.

BGFX_CAPS_CONSERVATIVE_RASTER

Conservative rasterization is supported.

BGFX_CAPS_DRAW_INDIRECT

Draw indirect is supported.

BGFX_CAPS_DRAW_INDIRECT_COUNT

Draw indirect with indirect count is supported.

BGFX_CAPS_FRAGMENT_DEPTH

Fragment depth is available in fragment shader.

BGFX_CAPS_FRAGMENT_ORDERING

Fragment ordering is available in fragment shader.

BGFX_CAPS_GRAPHICS_DEBUGGER

Graphics debugger is present.

BGFX_CAPS_HDR10

HDR10 rendering is supported.

BGFX_CAPS_HIDPI

HiDPI rendering is supported.

BGFX_CAPS_IMAGE_RW

Image Read/Write is supported.

BGFX_CAPS_INDEX32

32-bit indices are supported.

BGFX_CAPS_INSTANCING

Instancing is supported.

BGFX_CAPS_OCCLUSION_QUERY

Occlusion query is supported.

BGFX_CAPS_RENDERER_MULTITHREADED

Renderer is on separate thread.

BGFX_CAPS_SWAP_CHAIN

Multiple windows are supported.

BGFX_CAPS_TEXTURE_2D_ARRAY

2D texture array is supported.

BGFX_CAPS_TEXTURE_3D

3D textures are supported.

BGFX_CAPS_TEXTURE_BLIT

Texture blit is supported.

BGFX_CAPS_TEXTURE_COMPARE_ALL

BGFX_CAPS_TEXTURE_COMPARE_LEQUAL

Texture compare less equal mode is supported.

BGFX_CAPS_TEXTURE_CUBE_ARRAY

Cubemap texture array is supported.

BGFX_CAPS_TEXTURE_DIRECT_ACCESS

CPU direct access to GPU texture memory.

BGFX_CAPS_TEXTURE_READ_BACK

Read-back texture is supported.

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

Statistics

const Stats *bgfx::getStats()

Returns performance counters.

Attention

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

Attention

C99’s equivalent binding is bgfx_get_stats.

struct Stats

Renderer statistics data.

Remark

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

Attention

C99’s equivalent binding is bgfx_stats_t.

Public Members

int64_t cpuTimeFrame

CPU time between two bgfx::frame calls.

int64_t cpuTimeBegin

Render thread CPU submit begin time.

int64_t cpuTimeEnd

Render thread CPU submit end time.

int64_t cpuTimerFreq

CPU timer frequency. Timestamps-per-second.

int64_t gpuTimeBegin

GPU frame begin time.

int64_t gpuTimeEnd

GPU frame end time.

int64_t gpuTimerFreq

GPU timer frequency.

int64_t waitRender

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

int64_t waitSubmit

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

uint32_t numDraw

Number of draw calls submitted.

uint32_t numCompute

Number of compute calls submitted.

uint32_t numBlit

Number of blit calls submitted.

uint32_t maxGpuLatency

GPU driver latency.

uint32_t gpuFrameNum

Frame which generated gpuTimeBegin, gpuTimeEnd.

uint16_t numDynamicIndexBuffers

Number of used dynamic index buffers.

uint16_t numDynamicVertexBuffers

Number of used dynamic vertex buffers.

uint16_t numFrameBuffers

Number of used frame buffers.

uint16_t numIndexBuffers

Number of used index buffers.

uint16_t numOcclusionQueries

Number of used occlusion queries.

uint16_t numPrograms

Number of used programs.

uint16_t numShaders

Number of used shaders.

uint16_t numTextures

Number of used textures.

uint16_t numUniforms

Number of used uniforms.

uint16_t numVertexBuffers

Number of used vertex buffers.

uint16_t numVertexLayouts

Number of used vertex layouts.

int64_t textureMemoryUsed

Estimate of texture memory used.

int64_t rtMemoryUsed

Estimate of render target memory used.

int32_t transientVbUsed

Amount of transient vertex buffer used.

int32_t transientIbUsed

Amount of transient index buffer used.

uint32_t numPrims[Topology::Count]

Number of primitives rendered.

int64_t gpuMemoryMax

Maximum available GPU memory for application.

int64_t gpuMemoryUsed

Amount of GPU memory used by the application.

uint16_t width

Backbuffer width in pixels.

uint16_t height

Backbuffer height in pixels.

uint16_t textWidth

Debug text width in characters.

uint16_t textHeight

Debug text height in characters.

uint16_t numViews

Number of view stats.

ViewStats *viewStats

Array of View stats.

uint8_t numEncoders

Number of encoders used during frame.

EncoderStats *encoderStats

Array of encoder stats.

struct ViewStats

View stats.

Attention

C99’s equivalent binding is bgfx_view_stats_t.

Public Members

char name[256]

View name.

ViewId view

View id.

int64_t cpuTimeBegin

CPU (submit) begin time.

int64_t cpuTimeEnd

CPU (submit) end time.

int64_t gpuTimeBegin

GPU begin time.

int64_t gpuTimeEnd

GPU end time.

uint32_t gpuFrameNum

Frame which generated gpuTimeBegin, gpuTimeEnd.

struct EncoderStats

Encoder stats.

Attention

C99’s equivalent binding is bgfx_encoder_stats_t.

Public Members

int64_t cpuTimeBegin

Encoder thread CPU submit begin time.

int64_t cpuTimeEnd

Encoder thread CPU submit end time.

Platform specific

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

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

Render frame.

Attention

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

Attention

C99’s equivalent binding is bgfx_render_frame.

Warning

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

Parameters:

_msecs – Timeout in milliseconds.

Returns:

Current renderer state. See: bgfx::RenderFrame.

struct RenderFrame

Render frame enum.

Attention

C99’s equivalent binding is bgfx_render_frame_t.

void bgfx::setPlatformData(const PlatformData &_data)

Set platform data.

Attention

C99’s equivalent binding is bgfx_set_platform_data.

Warning

Must be called before bgfx::init.

struct PlatformData

Platform data.

Attention

C99’s equivalent binding is bgfx_platform_data_t.

Public Members

void *ndt

Native display type (*nix specific).

void *nwh

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

void *context

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

void *backBuffer

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

void *backBufferDS

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

NativeWindowHandleType::Enum type

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

const InternalData *bgfx::getInternalData()

Get internal data for interop.

Attention

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

Attention

C99’s equivalent binding is bgfx_get_internal_data.

Warning

Must be called only on render thread.

struct InternalData

Internal data.

Attention

C99’s equivalent binding is bgfx_internal_data_t.

Public Members

const struct Caps *caps

Renderer capabilities.

void *context

GL context, or D3D device.

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

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

Attention

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

Attention

C99’s equivalent binding is bgfx_override_internal_texture_ptr.

Warning

Must be called only on render thread.

Parameters:

• _handle – [in] Texture handle.

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

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

Returns:

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

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

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

Attention

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

Attention

C99’s equivalent binding is bgfx_override_internal_texture.

Warning

Must be called only on render thread.

Parameters:

• _handle – [in] Texture handle.

• _width – [in] Width.

• _height – [in] Height.

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

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

• _flags – [in] Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.

  • BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

Returns:

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

Miscellaneous

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

Pack vertex attribute into vertex stream format.

Attention

C99’s equivalent binding is bgfx_vertex_pack.

Parameters:

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

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

• _attr – [in] Attribute to pack.

• _layout – [in] Vertex stream layout.

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

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

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

Unpack vertex attribute from vertex stream format.

Attention

C99’s equivalent binding is bgfx_vertex_unpack.

Parameters:

• _output – [out] Result of unpacking.

• _attr – [in] Attribute to unpack.

• _layout – [in] Vertex stream layout.

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

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

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

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

Attention

C99’s equivalent binding is bgfx_vertex_convert.

Parameters:

• _destLayout – [in] Destination vertex stream layout.

• _destData – [in] Destination vertex stream.

• _srcLayout – [in] Source vertex stream layout.

• _srcData – [in] Source vertex stream data.

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

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

Weld vertices.

Attention

C99’s equivalent binding is bgfx_weld_vertices.

Parameters:

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

• _layout – [in] Vertex stream layout.

• _data – [in] Vertex stream.

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

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

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

Returns:

Number of unique vertices after vertex welding.

struct TopologyConvert

Topology conversion function.

Attention

C99’s equivalent binding is bgfx_topology_convert_t.

Public Types

enum Enum

Topology conversion functions:

Values:

enumerator TriListFlipWinding

Flip winding order of triangle list.

enumerator TriStripFlipWinding

Flip winding order of triangle strip.

enumerator TriListToLineList

Convert triangle list to line list.

enumerator TriStripToTriList

Convert triangle strip to triangle list.

enumerator LineStripToLineList

Convert line strip to line list.

enumerator Count

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

Convert index buffer for use with different primitive topologies.

Attention

C99’s equivalent binding is bgfx_topology_convert.

Parameters:

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

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

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

• _indices – [in] Source indices.

• _numIndices – [in] Number of input indices.

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

Returns:

Number of output indices after conversion.

struct TopologySort

Topology sort order.

Attention

C99’s equivalent binding is bgfx_topology_sort_t.

Public Types

enum Enum

Topology sort order:

Values:

enumerator DirectionFrontToBackMin

enumerator DirectionFrontToBackAvg

enumerator DirectionFrontToBackMax

enumerator DirectionBackToFrontMin

enumerator DirectionBackToFrontAvg

enumerator DirectionBackToFrontMax

enumerator DistanceFrontToBackMin

enumerator DistanceFrontToBackAvg

enumerator DistanceFrontToBackMax

enumerator DistanceBackToFrontMin

enumerator DistanceBackToFrontAvg

enumerator DistanceBackToFrontMax

enumerator Count

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

Sort indices.

Attention

C99’s equivalent binding is bgfx_topology_sort_tri_list.

Parameters:

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

• _dst – [in] Destination index buffer.

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

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

• _pos – [in] Position.

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

• _stride – [in] Vertex stride.

• _indices – [in] Source indices.

• _numIndices – [in] Number of input indices.

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

void bgfx::discard(uint8_t _flags = BGFX_DISCARD_ALL)

Discard all previously set state for draw or compute call.

Attention

C99’s equivalent binding is bgfx_discard.

Parameters:

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

void bgfx::touch(ViewId _id)

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

These empty draw calls will sort before ordinary draw calls.

Attention

C99’s equivalent binding is bgfx_touch.

Parameters:

_id – [in] View id.

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

Set palette color value.

Attention

C99’s equivalent binding is bgfx_set_palette_color.

Parameters:

• _index – [in] Index into palette.

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

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

Set palette color value.

Attention

C99’s equivalent binding is bgfx_set_palette_color.

Parameters:

• _index – [in] Index into palette.

• _rgba – [in] RGBA floating point value.

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

Set palette color value.

Attention

C99’s equivalent binding is bgfx_set_palette_color.

Parameters:

• _index – [in] Index into palette.

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

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

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

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

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

Request screen shot of window back buffer.

Remark

bgfx::CallbackI::screenShot must be implemented.

Attention

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

Attention

C99’s equivalent binding is bgfx_request_screen_shot.

Parameters:

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

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

Views

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

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

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

A View’s state is preserved between frames.

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

Set view name.

In graphics debugger view name will appear as:

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

Remark

This is debug only feature.

Attention

C99’s equivalent binding is bgfx_set_view_name.

Parameters:

• _id – [in] View id.

• _name – [in] View name.

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

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

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

Attention

C99’s equivalent binding is bgfx_set_view_rect.

Parameters:

• _id – [in] View id.

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

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

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

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

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

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

Attention

C99’s equivalent binding is bgfx_set_view_rect_ratio.

Parameters:

• _id – [in] View id.

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

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

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

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

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

Attention

C99’s equivalent binding is bgfx_set_view_scissor.

Parameters:

• _id – [in] View id.

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

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

• _width – [in] Width of scissor region.

• _height – [in] Height of scissor region.

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

Set view clear flags.

Attention

C99’s equivalent binding is bgfx_set_view_clear.

Parameters:

• _id – [in] View id.

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

• _rgba – [in] Color clear value.

• _depth – [in] Depth clear value.

• _stencil – [in] Stencil clear value.

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

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

Attention

C99’s equivalent binding is bgfx_set_view_clear_mrt.

Parameters:

• _id – [in] View id.

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

• _depth – [in] Depth clear value.

• _stencil – [in] Stencil clear value.

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

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

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

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

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

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

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

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

struct ViewMode

View mode sets draw call sort order.

Attention

C99’s equivalent binding is bgfx_view_mode_t.

Public Types

enum Enum

View modes:

Values:

enumerator Default

Default sort order.

enumerator Sequential

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

enumerator DepthAscending

Sort draw call depth in ascending order.

enumerator DepthDescending

Sort draw call depth in descending order.

enumerator Count

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

Set view sorting mode.

Remark

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

Attention

C99’s equivalent binding is bgfx_set_view_mode.

Parameters:

• _id – [in] View id.

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

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

Set view frame buffer.

Remark

Not persistent after bgfx::reset call.

Attention

C99’s equivalent binding is bgfx_set_view_frame_buffer.

Parameters:

• _id – [in] View id.

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

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

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

Attention

C99’s equivalent binding is bgfx_set_view_transform.

Parameters:

• _id – [in] View id.

• _view – [in] View matrix.

• _proj – [in] Projection matrix.

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

Post submit view reordering.

Attention

C99’s equivalent binding is bgfx_set_view_order.

Parameters:

• _id – [in] First view id.

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

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

void bgfx::resetView(ViewId _id)

Reset all view settings to default.

Attention

C99’s equivalent binding is bgfx_reset_view.

Parameters:

_id – [in] View id.

Encoder

Encoder

API for multi-threaded submission.

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

Begin submitting draw calls from thread.

Parameters:

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

void bgfx::end(Encoder *_encoder)

End submitting draw calls from thread.

struct Encoder

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

Attention

C99’s equivalent binding is bgfx_encoder.

Public Functions

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

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

Attention

C99’s equivalent binding is bgfx_encoder_set_marker.

Parameters:

• _name – [in] Marker name.

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

void setState(uint64_t _state, uint32_t _rgba = 0)

Set render states for draw primitive.

Remark

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

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

Attention

C99’s equivalent binding is bgfx_encoder_set_state.

Parameters:

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

  • BGFX_STATE_DEPTH_TEST_* - Depth test function.

  • BGFX_STATE_BLEND_* - See remark 1 about BGFX_STATE_BLEND_FUNC.

  • BGFX_STATE_BLEND_EQUATION_* - See remark 2.

  • BGFX_STATE_CULL_* - Backface culling mode.

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

  • BGFX_STATE_MSAA - Enable hardware multisample antialiasing.

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

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

void setCondition(OcclusionQueryHandle _handle, bool _visible)

Set condition for rendering.

Attention

C99’s equivalent binding is bgfx_encoder_set_condition.

Parameters:

• _handle – [in] Occlusion query handle.

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

void setStencil(uint32_t _fstencil, uint32_t _bstencil = BGFX_STENCIL_NONE)

Set stencil test state.

Attention

C99’s equivalent binding is bgfx_encoder_set_stencil.

Parameters:

• _fstencil – [in] Front stencil state.

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

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

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

Attention

C99’s equivalent binding is bgfx_encoder_set_scissor.

Parameters:

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

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

• _width – [in] Width of scissor region.

• _height – [in] Height of scissor region.

Returns:

Scissor cache index.

void setScissor(uint16_t _cache = UINT16_MAX)

Set scissor from cache for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_scissor_cached.

Parameters:

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

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

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

Attention

C99’s equivalent binding is bgfx_encoder_set_transform.

Parameters:

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

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

Returns:

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

uint32_t allocTransform(Transform *_transform, uint16_t _num)

Reserve _num matrices in internal matrix cache.

Attention

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

Attention

C99’s equivalent binding is bgfx_encoder_alloc_transform.

Parameters:

• _transform – [in] Pointer to Transform structure.

• _num – [in] Number of matrices.

Returns:

Index into matrix cache.

void setTransform(uint32_t _cache, uint16_t _num = 1)

Set model matrix from matrix cache for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_transform_cached.

Parameters:

• _cache – [in] Index in matrix cache.

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

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

Set shader uniform parameter for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_uniform.

Parameters:

• _handle – [in] Uniform.

• _value – [in] Pointer to uniform data.

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

void setIndexBuffer(IndexBufferHandle _handle)

Set index buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_index_buffer.

Parameters:

_handle – [in] Index buffer.

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

Set index buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_index_buffer.

Parameters:

• _handle – [in] Index buffer.

• _firstIndex – [in] First index to render.

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

void setIndexBuffer(DynamicIndexBufferHandle _handle)

Set index buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_dynamic_index_buffer.

Parameters:

_handle – [in] Dynamic index buffer.

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

Set index buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_dynamic_index_buffer.

Parameters:

• _handle – [in] Dynamic index buffer.

• _firstIndex – [in] First index to render.

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

void setIndexBuffer(const TransientIndexBuffer *_tib)

Set index buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_transient_index_buffer.

Parameters:

_tib – [in] Transient index buffer.

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

Set index buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_transient_index_buffer.

Parameters:

• _tib – [in] Transient index buffer.

• _firstIndex – [in] First index to render.

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

void setVertexBuffer(uint8_t _stream, VertexBufferHandle _handle)

Set vertex buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_vertex_buffer.

Parameters:

• _stream – [in] Vertex stream.

• _handle – [in] Vertex buffer.

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

Set vertex buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_vertex_buffer.

Parameters:

• _stream – [in] Vertex stream.

• _handle – [in] Vertex buffer.

• _startVertex – [in] First vertex to render.

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

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

void setVertexBuffer(uint8_t _stream, DynamicVertexBufferHandle _handle)

Set vertex buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_dynamic_vertex_buffer.

Parameters:

• _stream – [in] Vertex stream.

• _handle – [in] Dynamic vertex buffer.

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

Set vertex buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_dynamic_vertex_buffer.

Parameters:

• _stream – [in] Vertex stream.

• _handle – [in] Dynamic vertex buffer.

• _startVertex – [in] First vertex to render.

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

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

void setVertexBuffer(uint8_t _stream, const TransientVertexBuffer *_tvb)

Set vertex buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_transient_vertex_buffer.

Parameters:

• _stream – [in] Vertex stream.

• _tvb – [in] Transient vertex buffer.

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

Set vertex buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_transient_vertex_buffer.

Parameters:

• _stream – [in] Vertex stream.

• _tvb – [in] Transient vertex buffer.

• _startVertex – [in] First vertex to render.

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

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

void setVertexCount(uint32_t _numVertices)

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

Attention

Availability depends on: BGFX_CAPS_VERTEX_ID.

Attention

C99’s equivalent binding is bgfx_encoder_set_vertex_count.

Parameters:

_numVertices – [in] Number of vertices.

void setInstanceDataBuffer(const InstanceDataBuffer *_idb)

Set instance data buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_instance_data_buffer.

Parameters:

_idb – [in] Transient instance data buffer.

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

Set instance data buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_instance_data_buffer.

Parameters:

• _idb – [in] Transient instance data buffer.

• _start – [in] First instance data.

• _num – [in] Number of data instances.

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

Set instance data buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_instance_data_from_vertex_buffer.

Parameters:

• _handle – [in] Vertex buffer.

• _start – [in] First instance data.

• _num – [in] Number of data instances.

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

Set instance data buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_instance_data_from_dynamic_vertex_buffer.

Parameters:

• _handle – [in] Vertex buffer.

• _start – [in] First instance data.

• _num – [in] Number of data instances.

void setInstanceCount(uint32_t _numInstances)

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

Attention

Availability depends on: BGFX_CAPS_VERTEX_ID.

Attention

C99’s equivalent binding is bgfx_encoder_set_instance_count.

Parameters:

_numInstances – [in] Number of instances.

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

Set texture stage for draw primitive.

Attention

C99’s equivalent binding is bgfx_encoder_set_texture.

Parameters:

• _stage – [in] Texture unit.

• _sampler – [in] Program sampler.

• _handle – [in] Texture handle.

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

  • BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.

  • BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

void touch(ViewId _id)

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

These empty draw calls will sort before ordinary draw calls.

Attention

C99’s equivalent binding is bgfx_encoder_touch.

Parameters:

_id – [in] View id.

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

Submit primitive for rendering.

Attention

C99’s equivalent binding is bgfx_encoder_submit.

Parameters:

• _id – [in] View id.

• _program – [in] Program.

• _depth – [in] Depth for sorting.

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

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

Submit primitive with occlusion query for rendering.

Attention

C99’s equivalent binding is bgfx_encoder_submit_occlusion_query.

Parameters:

• _id – [in] View id.

• _program – [in] Program.

• _occlusionQuery – [in] Occlusion query.

• _depth – [in] Depth for sorting.

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

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

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

Attention

Availability depends on: BGFX_CAPS_DRAW_INDIRECT.

Attention

C99’s equivalent binding is bgfx_encoder_submit_indirect.

Parameters:

• _id – [in] View id.

• _program – [in] Program.

• _indirectHandle – [in] Indirect buffer.

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

• _num – [in] Number of draws.

• _depth – [in] Depth for sorting.

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

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

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

Attention

Availability depends on: BGFX_CAPS_DRAW_INDIRECT_COUNT.

Attention

C99’s equivalent binding is bgfx_encoder_submit_indirect_count.

Parameters:

• _id – [in] View id.

• _program – [in] Program.

• _indirectHandle – [in] Indirect buffer.

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

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

• _numIndex – [in] Element in number buffer.

• _numMax – [in] Max number of draws.

• _depth – [in] Depth for sorting.

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

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

Set compute index buffer.

Attention

C99’s equivalent binding is bgfx_encoder_set_compute_index_buffer.

Parameters:

• _stage – [in] Compute stage.

• _handle – [in] Index buffer handle.

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

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

Set compute vertex buffer.

Attention

C99’s equivalent binding is bgfx_encoder_set_compute_vertex_buffer.

Parameters:

• _stage – [in] Compute stage.

• _handle – [in] Vertex buffer handle.

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

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

Set compute dynamic index buffer.

Attention

C99’s equivalent binding is bgfx_encoder_set_compute_dynamic_index_buffer.

Parameters:

• _stage – [in] Compute stage.

• _handle – [in] Dynamic index buffer handle.

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

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

Set compute dynamic vertex buffer.

Attention

C99’s equivalent binding is bgfx_encoder_set_compute_dynamic_vertex_buffer.

Parameters:

• _stage – [in] Compute stage.

• _handle – [in] Dynamic vertex buffer handle.

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

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

Set compute indirect buffer.

Attention

C99’s equivalent binding is bgfx_encoder_set_compute_indirect_buffer.

Parameters:

• _stage – [in] Compute stage.

• _handle – [in] Indirect buffer handle.

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

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

Set compute image from texture.

Attention

C99’s equivalent binding is bgfx_encoder_set_image.

Parameters:

• _stage – [in] Texture unit.

• _handle – [in] Texture handle.

• _mip – [in] Mip level.

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

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

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

Dispatch compute.

Attention

C99’s equivalent binding is bgfx_encoder_dispatch.

Parameters:

• _id – [in] View id.

• _handle – [in] Compute program.

• _numX – [in] Number of groups X.

• _numY – [in] Number of groups Y.

• _numZ – [in] Number of groups Z.

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

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

Dispatch compute indirect.

Attention

C99’s equivalent binding is bgfx_encoder_dispatch_indirect.

Parameters:

• _id – [in] View id.

• _handle – [in] Compute program.

• _indirectHandle – [in] Indirect buffer.

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

• _num – [in] Number of dispatches.

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

void discard(uint8_t _flags = BGFX_DISCARD_ALL)

Discard all previously set state for draw or compute call.

Attention

C99’s equivalent binding is bgfx_encoder_discard.

Parameters:

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

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

Blit texture 2D region between two 2D textures.

Attention

Destination texture must be created with BGFX_TEXTURE_BLIT_DST flag.

Attention

Availability depends on: BGFX_CAPS_TEXTURE_BLIT.

Attention

C99’s equivalent binding is bgfx_encoder_blit.

Parameters:

• _id – [in] View id.

• _dst – [in] Destination texture handle.

• _dstX – [in] Destination texture X position.

• _dstY – [in] Destination texture Y position.

• _src – [in] Source texture handle.

• _srcX – [in] Source texture X position.

• _srcY – [in] Source texture Y position.

• _width – [in] Width of region.

• _height – [in] Height of region.

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

Blit texture region between two textures.

Attention

Destination texture must be created with BGFX_TEXTURE_BLIT_DST flag.

Attention

Availability depends on: BGFX_CAPS_TEXTURE_BLIT.

Attention

C99’s equivalent binding is bgfx_encoder_blit.

Parameters:

• _id – [in] View id.

• _dst – [in] Destination texture handle.

• _dstMip – [in] Destination texture mip level.

• _dstX – [in] Destination texture X position.

• _dstY – [in] Destination texture Y position.

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

• _src – [in] Source texture handle.

• _srcMip – [in] Source texture mip level.

• _srcX – [in] Source texture X position.

• _srcY – [in] Source texture Y position.

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

• _width – [in] Width of region.

• _height – [in] Height of region.

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

Draw

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

State

Debug

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

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

Attention

C99’s equivalent binding is bgfx_set_marker.

Parameters:

• _name – [in] Marker name.

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

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

Set shader debug name.

Attention

C99’s equivalent binding is bgfx_set_shader_name.

Parameters:

• _handle – [in] Shader handle.

• _name – [in] Shader name.

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

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

Set texture debug name.

Attention

C99’s equivalent binding is bgfx_set_texture_name.

Parameters:

• _handle – [in] Texture handle.

• _name – [in] Texture name.

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

State

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

Set render states for draw primitive.

Remark

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

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

Attention

C99’s equivalent binding is bgfx_set_state.

Parameters:

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

  • BGFX_STATE_DEPTH_TEST_* - Depth test function.

  • BGFX_STATE_BLEND_* - See remark 1 about BGFX_STATE_BLEND_FUNC.

  • BGFX_STATE_BLEND_EQUATION_* - See remark 2.

  • BGFX_STATE_CULL_* - Backface culling mode.

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

  • BGFX_STATE_MSAA - Enable MSAA.

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

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

State Flags

Write

BGFX_STATE_WRITE_R

Enable R write.

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

BGFX_STATE_WRITE_G

Enable G write.

BGFX_STATE_WRITE_B

Enable B write.

BGFX_STATE_WRITE_RGB

BGFX_STATE_WRITE_A

Enable alpha write.

BGFX_STATE_WRITE_Z

Enable depth write. Enable RGB write.

Depth Test

BGFX_STATE_DEPTH_TEST_LESS

Enable depth test, less.

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

BGFX_STATE_DEPTH_TEST_LEQUAL

Enable depth test, less or equal.

BGFX_STATE_DEPTH_TEST_EQUAL

Enable depth test, equal.

BGFX_STATE_DEPTH_TEST_GEQUAL

Enable depth test, greater or equal.

BGFX_STATE_DEPTH_TEST_GREATER

Enable depth test, greater.

BGFX_STATE_DEPTH_TEST_NOTEQUAL

Enable depth test, not equal.

BGFX_STATE_DEPTH_TEST_NEVER

Enable depth test, never.

BGFX_STATE_DEPTH_TEST_ALWAYS

Enable depth test, always.

Blend Mode

BGFX_STATE_BLEND_ZERO

0, 0, 0, 0

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

BGFX_STATE_BLEND_ONE

1, 1, 1, 1

BGFX_STATE_BLEND_SRC_COLOR

Rs, Gs, Bs, As.

BGFX_STATE_BLEND_INV_SRC_COLOR

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

BGFX_STATE_BLEND_SRC_ALPHA

As, As, As, As.

BGFX_STATE_BLEND_INV_SRC_ALPHA

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

BGFX_STATE_BLEND_DST_ALPHA

Ad, Ad, Ad, Ad.

BGFX_STATE_BLEND_INV_DST_ALPHA

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

BGFX_STATE_BLEND_DST_COLOR

Rd, Gd, Bd, Ad.

BGFX_STATE_BLEND_INV_DST_COLOR

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

BGFX_STATE_BLEND_SRC_ALPHA_SAT

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

BGFX_STATE_BLEND_FACTOR

Blend factor.

BGFX_STATE_BLEND_INV_FACTOR

1-Blend factor

Blend Equation

BGFX_STATE_BLEND_EQUATION_ADD

Blend add: src + dst.

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

BGFX_STATE_BLEND_EQUATION_SUB

Blend subtract: src - dst.

BGFX_STATE_BLEND_EQUATION_REVSUB

Blend reverse subtract: dst - src.

BGFX_STATE_BLEND_EQUATION_MIN

Blend min: min(src, dst).

BGFX_STATE_BLEND_EQUATION_MAX

Blend max: max(src, dst).

Primitive Culling

BGFX_STATE_CULL_CW

Cull clockwise triangles.

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

BGFX_STATE_CULL_CCW

Cull counter-clockwise triangles.

Primitive Type

BGFX_STATE_PT_TRISTRIP

Tristrip.

BGFX_STATE_PT_LINES

Lines.

BGFX_STATE_PT_LINESTRIP

Line strip.

BGFX_STATE_PT_POINTS

Points.

Misc

BGFX_STATE_BLEND_INDEPENDENT

Enable blend independent.

BGFX_STATE_BLEND_ALPHA_TO_COVERAGE

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

BGFX_STATE_MSAA

Enable MSAA rasterization.

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

BGFX_STATE_LINEAA

Enable line AA rasterization.

Stencil

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

Set stencil test state.

Attention

C99’s equivalent binding is bgfx_set_stencil.

Parameters:

• _fstencil – [in] Front stencil state.

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

Stencil Flags

BGFX_STENCIL_TEST_LESS

Enable stencil test, less.

Scissor

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

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

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

Attention

C99’s equivalent binding is bgfx_set_scissor.

Parameters:

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

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

• _width – [in] Width of scissor region.

• _height – [in] Height of scissor region.

Returns:

Scissor cache index.

void bgfx::setScissor(uint16_t _cache = UINT16_MAX)

Set scissor from cache for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_scissor_cached.

Parameters:

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

Transform

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

Reserve _num matrices in internal matrix cache.

Attention

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

Attention

C99’s equivalent binding is bgfx_alloc_transform.

Parameters:

• _transform – [in] Pointer to Transform structure.

• _num – [in] Number of matrices.

Returns:

index into matrix cache.

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

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

Attention

C99’s equivalent binding is bgfx_set_transform.

Parameters:

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

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

Returns:

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

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

Set model matrix from matrix cache for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_transform_cached.

Parameters:

• _cache – [in] Index in matrix cache.

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

Conditional Rendering

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

Set condition for rendering.

Attention

C99’s equivalent binding is bgfx_set_condition.

Parameters:

• _handle – [in] Occlusion query handle.

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

Buffers

void bgfx::setIndexBuffer(IndexBufferHandle _handle)

Set index buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_index_buffer.

Parameters:

_handle – [in] Index buffer.

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

Set index buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_index_buffer.

Parameters:

• _handle – [in] Index buffer.

• _firstIndex – [in] First index to render.

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

void bgfx::setIndexBuffer(DynamicIndexBufferHandle _handle)

Set index buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_dynamic_index_buffer.

Parameters:

_handle – [in] Dynamic index buffer.

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

Set index buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_dynamic_index_buffer.

Parameters:

• _handle – [in] Dynamic index buffer.

• _firstIndex – [in] First index to render.

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

struct TransientIndexBuffer

Transient index buffer.

Attention

C99’s equivalent binding is bgfx_transient_index_buffer_t.

Public Members

uint8_t *data

Pointer to data.

uint32_t size

Data size.

uint32_t startIndex

First index.

IndexBufferHandle handle

Index buffer handle.

bool isIndex16

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

void bgfx::setIndexBuffer(const TransientIndexBuffer *_tib)

Set index buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_transient_index_buffer.

Parameters:

_tib – [in] Transient index buffer.

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

Set index buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_transient_index_buffer.

Parameters:

• _tib – [in] Transient index buffer.

• _firstIndex – [in] First index to render.

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

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

Set vertex buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_vertex_buffer.

Parameters:

• _stream – [in] Vertex stream.

• _handle – [in] Vertex buffer.

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

Set vertex buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_vertex_buffer.

Parameters:

• _stream – [in] Vertex stream.

• _handle – [in] Vertex buffer.

• _startVertex – [in] First vertex to render.

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

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

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

Set vertex buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_dynamic_vertex_buffer.

Parameters:

• _stream – [in] Vertex stream.

• _handle – [in] Dynamic vertex buffer.

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

Set vertex buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_dynamic_vertex_buffer.

Parameters:

• _stream – [in] Vertex stream.

• _handle – [in] Dynamic vertex buffer.

• _startVertex – [in] First vertex to render.

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

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

struct TransientVertexBuffer

Transient vertex buffer.

Attention

C99’s equivalent binding is bgfx_transient_vertex_buffer_t.

Public Members

uint8_t *data

Pointer to data.

uint32_t size

Data size.

uint32_t startVertex

First vertex.

uint16_t stride

Vertex stride.

VertexBufferHandle handle

Vertex buffer handle.

VertexLayoutHandle layoutHandle

Vertex layout handle.

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

Set vertex buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_transient_vertex_buffer.

Parameters:

• _stream – [in] Vertex stream.

• _tvb – [in] Transient vertex buffer.

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

Set vertex buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_transient_vertex_buffer.

Parameters:

• _stream – [in] Vertex stream.

• _tvb – [in] Transient vertex buffer.

• _startVertex – [in] First vertex to render.

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

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

void bgfx::setVertexCount(uint32_t _numVertices)

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

Attention

Availability depends on: BGFX_CAPS_VERTEX_ID.

Attention

C99’s equivalent binding is bgfx_set_vertex_count.

Parameters:

_numVertices – [in] Number of vertices.

struct InstanceDataBuffer

Instance data buffer info.

Attention

C99’s equivalent binding is bgfx_instance_data_buffer_t.

Public Members

uint8_t *data

Pointer to data.

uint32_t size

Data size.

uint32_t offset

Offset in vertex buffer.

uint32_t num

Number of instances.

uint16_t stride

Vertex buffer stride.

VertexBufferHandle handle

Vertex buffer object handle.

void bgfx::setInstanceDataBuffer(const InstanceDataBuffer *_idb)

Set instance data buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_instance_data_buffer.

Parameters:

_idb – [in] Transient instance data buffer.

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

Set instance data buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_instance_data_buffer.

Parameters:

• _idb – [in] Transient instance data buffer.

• _start – [in] First instance data.

• _num – [in] Number of data instances.

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

Set instance data buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_instance_data_from_vertex_buffer.

Parameters:

• _handle – [in] Vertex buffer.

• _start – [in] First instance data.

• _num – [in] Number of data instances.

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

Set instance data buffer for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_instance_data_from_dynamic_vertex_buffer.

Parameters:

• _handle – [in] Vertex buffer.

• _start – [in] First instance data.

• _num – [in] Number of data instances.

void bgfx::setInstanceCount(uint32_t _numInstances)

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

Attention

Availability depends on: BGFX_CAPS_VERTEX_ID.

Attention

C99’s equivalent binding is bgfx_set_instance_count.

Parameters:

_numInstances – [in] Number of instances.

Textures

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

Set texture stage for draw primitive.

Attention

C99’s equivalent binding is bgfx_set_texture.

Parameters:

• _stage – [in] Texture unit.

• _sampler – [in] Program sampler.

• _handle – [in] Texture handle.

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

  • BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.

  • BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

Submit

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

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

Submit primitive for rendering.

Attention

C99’s equivalent binding is bgfx_submit.

Parameters:

• _id – [in] View id.

• _program – [in] Program.

• _depth – [in] Depth for sorting.

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

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

Submit primitive with occlusion query for rendering.

Attention

C99’s equivalent binding is bgfx_submit_occlusion_query.

Parameters:

• _id – [in] View id.

• _program – [in] Program.

• _occlusionQuery – [in] Occlusion query.

• _depth – [in] Depth for sorting.

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

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

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

Attention

Availability depends on: BGFX_CAPS_DRAW_INDIRECT.

Attention

C99’s equivalent binding is bgfx_submit_indirect.

Parameters:

• _id – [in] View id.

• _program – [in] Program.

• _indirectHandle – [in] Indirect buffer.

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

• _num – [in] Number of draws.

• _depth – [in] Depth for sorting.

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

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

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

Attention

Availability depends on:BGFX_CAPS_DRAW_INDIRECT_COUNT.

Attention

C99’s equivalent binding is bgfx_submit_indirect_count.

Parameters:

• _id – [in] View id.

• _program – [in] Program.

• _indirectHandle – [in] Indirect buffer.

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

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

• _numIndex – [in] Element in number buffer.

• _numMax – [in] Max number of draws.

• _depth – [in] Depth for sorting.

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

Compute

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

Buffers

struct Access

Access mode enum.

Attention

C99’s equivalent binding is bgfx_access_t.

Public Types

enum Enum

Access:

Values:

enumerator Read

Read.

enumerator Write

Write.

enumerator ReadWrite

Read and write.

enumerator Count

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

Set compute index buffer.

Attention

C99’s equivalent binding is bgfx_set_compute_index_buffer.

Parameters:

• _stage – [in] Compute stage.

• _handle – [in] Index buffer handle.

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

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

Set compute vertex buffer.

Attention

C99’s equivalent binding is bgfx_set_compute_vertex_buffer.

Parameters:

• _stage – [in] Compute stage.

• _handle – [in] Vertex buffer handle.

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

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

Set compute dynamic index buffer.

Attention

C99’s equivalent binding is bgfx_set_compute_dynamic_index_buffer.

Parameters:

• _stage – [in] Compute stage.

• _handle – [in] Dynamic index buffer handle.

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

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

Set compute dynamic vertex buffer.

Attention

C99’s equivalent binding is bgfx_set_compute_dynamic_vertex_buffer.

Parameters:

• _stage – [in] Compute stage.

• _handle – [in] Dynamic vertex buffer handle.

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

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

Set compute indirect buffer.

Attention

C99’s equivalent binding is bgfx_set_compute_indirect_buffer.

Parameters:

• _stage – [in] Compute stage.

• _handle – [in] Indirect buffer handle.

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

Images

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

Set compute image from texture.

Attention

C99’s equivalent binding is bgfx_set_image.

Parameters:

• _stage – [in] Texture unit.

• _handle – [in] Texture handle.

• _mip – [in] Mip level.

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

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

Dispatch

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

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

Dispatch compute.

Attention

C99’s equivalent binding is bgfx_dispatch.

Parameters:

• _id – [in] View id.

• _handle – [in] Compute program.

• _numX – [in] Number of groups X.

• _numY – [in] Number of groups Y.

• _numZ – [in] Number of groups Z.

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

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

Dispatch compute indirect.

Attention

C99’s equivalent binding is bgfx_dispatch_indirect.

Parameters:

• _id – [in] View id.

• _handle – [in] Compute program.

• _indirectHandle – [in] Indirect buffer.

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

• _num – [in] Number of dispatches.

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

Blit

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

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

Blit 2D texture region between two 2D textures.

Attention

Destination texture must be created with BGFX_TEXTURE_BLIT_DST flag.

Attention

Availability depends on: BGFX_CAPS_TEXTURE_BLIT.

Attention

C99’s equivalent binding is bgfx_blit.

Parameters:

• _id – [in] View id.

• _dst – [in] Destination texture handle.

• _dstX – [in] Destination texture X position.

• _dstY – [in] Destination texture Y position.

• _src – [in] Source texture handle.

• _srcX – [in] Source texture X position.

• _srcY – [in] Source texture Y position.

• _width – [in] Width of region.

• _height – [in] Height of region.

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

Blit texture region between two textures.

Attention

Destination texture must be created with BGFX_TEXTURE_BLIT_DST flag.

Attention

Availability depends on: BGFX_CAPS_TEXTURE_BLIT.

Attention

C99’s equivalent binding is bgfx_blit.

Parameters:

• _id – [in] View id.

• _dst – [in] Destination texture handle.

• _dstMip – [in] Destination texture mip level.

• _dstX – [in] Destination texture X position.

• _dstY – [in] Destination texture Y position.

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

• _src – [in] Source texture handle.

• _srcMip – [in] Source texture mip level.

• _srcX – [in] Source texture X position.

• _srcY – [in] Source texture Y position.

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

• _width – [in] Width of region.

• _height – [in] Height of region.

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

Resources

struct Memory

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

Attention

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

Attention

C99’s equivalent binding is bgfx_memory_t.

Public Members

uint8_t *data

Pointer to data.

uint32_t size

Data size.

const Memory *bgfx::alloc(uint32_t _size)

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

Attention

C99’s equivalent binding is bgfx_alloc.

Parameters:

_size – [in] Size to allocate.

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

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

Attention

C99’s equivalent binding is bgfx_copy.

Parameters:

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

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

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

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

Attention

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

Attention

C99’s equivalent bindings are bgfx_make_ref, bgfx_make_ref_release.

Parameters:

• _data – [in] Pointer to data.

• _size – [in] Size of data.

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

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

Shaders and Programs

Note

Shaders must be compiled with offline command line too shaderc.

ShaderHandle bgfx::createShader(const Memory *_mem)

Create shader from memory buffer.

Remark

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

Attention

C99’s equivalent binding is bgfx_create_shader.

Returns:

Shader handle.

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

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

Remark

Only non-predefined uniforms are returned.

Attention

C99’s equivalent binding is bgfx_get_shader_uniforms.

Parameters:

• _handle – [in] Shader handle.

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

• _max – [in] Maximum capacity of array.

Returns:

Number of uniforms used by shader.

void bgfx::destroy(ShaderHandle _handle)

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

Attention

C99’s equivalent binding is bgfx_destroy_shader.

Parameters:

_handle – [in] Shader handle.

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

Create program with vertex and fragment shaders.

Attention

C99’s equivalent binding is bgfx_create_program.

Parameters:

• _vsh – [in] Vertex shader.

• _fsh – [in] Fragment shader.

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

Returns:

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

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

Create program with compute shader.

Attention

C99’s equivalent binding is bgfx_create_compute_program.

Parameters:

• _csh – [in] Compute shader.

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

Returns:

Program handle.

void bgfx::destroy(ProgramHandle _handle)

Destroy program.

Attention

C99’s equivalent binding is bgfx_destroy_program.

Parameters:

_handle – [in] Program handle.

Uniforms

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

Create shader uniform parameter.

• u_modelViewProj mat4 - concatenated model view projection matrix.

  • u_alphaRef float - alpha reference value for alpha test.

Remark

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

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

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

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

   • u_view mat4 - view matrix

   • u_invView mat4 - inverted view matrix

   • u_proj mat4 - projection matrix

   • u_invProj mat4 - inverted projection matrix

   • u_viewProj mat4 - concatenated view projection matrix

   • u_invViewProj mat4 - concatenated inverted view projection matrix

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

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

Attention

C99’s equivalent binding is bgfx_create_uniform.

Parameters:

• _name – [in] Uniform name in shader.

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

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

Returns:

Handle to uniform object.

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.

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

Vertex Buffers

VertexLayoutHandle bgfx::createVertexLayout(const VertexLayout &_layout)

Create vertex layout.

Attention

C99’s equivalent binding is bgfx_create_vertex_layout.

void bgfx::destroy(VertexLayoutHandle _handle)

Destroy vertex layout.

Attention

C99’s equivalent binding is bgfx_destroy_vertex_layout.

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

Create static vertex buffer.

Attention

C99’s equivalent binding is bgfx_create_vertex_buffer.

Parameters:

• _mem – [in] Vertex buffer data.

• _layout – [in] Vertex layout.

• _flags – [in] Buffer creation flags.

  • BGFX_BUFFER_NONE - No flags.

  • BGFX_BUFFER_COMPUTE_READ - Buffer will be read from by compute shader.

  • BGFX_BUFFER_COMPUTE_WRITE - Buffer will be written into by compute shader. When buffer is created with BGFX_BUFFER_COMPUTE_WRITE flag it cannot be updated from CPU.

  • BGFX_BUFFER_COMPUTE_READ_WRITE - Buffer will be used for read/write by compute shader.

  • BGFX_BUFFER_ALLOW_RESIZE - Buffer will resize on buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.

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

Returns:

Static vertex buffer handle.

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

Set static vertex buffer debug name.

Attention

C99’s equivalent binding is bgfx_set_vertex_buffer_name.

Parameters:

• _handle – [in] Static vertex buffer handle.

• _name – [in] Static vertex buffer name.

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

void bgfx::destroy(VertexBufferHandle _handle)

Destroy static vertex buffer.

Attention

C99’s equivalent binding is bgfx_destroy_vertex_buffer.

Parameters:

_handle – [in] Static vertex buffer handle.

struct VertexLayout

Vertex layout.

Attention

C99’s equivalent binding is bgfx_vertex_layout_t.

Public Functions

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

Start VertexLayout.

Attention

C99’s equivalent binding is bgfx_vertex_layout_begin.

Parameters:

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

Returns:

Returns itself.

void end()

End VertexLayout.

Attention

C99’s equivalent binding is bgfx_vertex_layout_end.

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

Add attribute to VertexLayout.

Remark

Must be called between begin/end.

Attention

C99’s equivalent binding is bgfx_vertex_layout_add.

Parameters:

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

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

• _type – [in] Element type.

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

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

Returns:

Returns itself.

VertexLayout &skip(uint8_t _num)

Skip _num bytes in vertex stream.

Attention

C99’s equivalent binding is bgfx_vertex_layout_skip.

Returns:

Returns itself.

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

Decode attribute.

Attention

C99’s equivalent binding is bgfx_vertex_layout_decode.

inline bool has(Attrib::Enum _attrib) const

Returns true if VertexLayout contains attribute.

Attention

C99’s equivalent binding is bgfx_vertex_layout_has.

Parameters:

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

Returns:

True if VertexLayout contains attribute.

inline uint16_t getOffset(Attrib::Enum _attrib) const

Returns relative attribute offset from the vertex.

Parameters:

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

Returns:

Relative attribute offset from the vertex.

inline uint16_t getStride() const

Returns vertex stride.

Returns:

Vertex stride.

inline uint32_t getSize(uint32_t _num) const

Returns size of vertex buffer for number of vertices.

Parameters:

_num – [in] Number of vertices.

Returns:

Size of vertex buffer for number of vertices.

Public Members

uint32_t m_hash

Hash.

uint16_t m_stride

Stride.

uint16_t m_offset[Attrib::Count]

Attribute offsets.

uint16_t m_attributes[Attrib::Count]

Used attributes.

struct Attrib

Vertex attribute enum.

Attention

C99’s equivalent binding is bgfx_attrib_t.

Public Types

enum Enum

Corresponds to vertex shader attribute.

Values:

enumerator Position

a_position

enumerator Normal

a_normal

enumerator Tangent

a_tangent

enumerator Bitangent

a_bitangent

enumerator Color0

a_color0

enumerator Color1

a_color1

enumerator Color2

a_color2

enumerator Color3

a_color3

enumerator Indices

a_indices

enumerator Weight

a_weight

enumerator TexCoord0

a_texcoord0

enumerator TexCoord1

a_texcoord1

enumerator TexCoord2

a_texcoord2

enumerator TexCoord3

a_texcoord3

enumerator TexCoord4

a_texcoord4

enumerator TexCoord5

a_texcoord5

enumerator TexCoord6

a_texcoord6

enumerator TexCoord7

a_texcoord7

enumerator Count

struct AttribType

Vertex attribute type enum.

Attention

C99’s equivalent binding is bgfx_attrib_type_t.

Public Types

enum Enum

Attribute types:

Values:

enumerator Uint8

Uint8.

enumerator Uint10

Uint10, availability depends on: BGFX_CAPS_VERTEX_ATTRIB_UINT10.

enumerator Int16

Int16.

enumerator Half

Half, availability depends on: BGFX_CAPS_VERTEX_ATTRIB_HALF.

enumerator Float

Float.

enumerator Count

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

Create empty dynamic vertex buffer.

Attention

C99’s equivalent binding is bgfx_create_dynamic_vertex_buffer.

Parameters:

• _num – [in] Number of vertices.

• _layout – [in] Vertex layout.

• _flags – [in] Buffer creation flags.

  • BGFX_BUFFER_NONE - No flags.

  • BGFX_BUFFER_COMPUTE_READ - Buffer will be read from by compute shader.

  • BGFX_BUFFER_COMPUTE_WRITE - Buffer will be written into by compute shader. When buffer is created with BGFX_BUFFER_COMPUTE_WRITE flag it cannot be updated from CPU.

  • BGFX_BUFFER_COMPUTE_READ_WRITE - Buffer will be used for read/write by compute shader.

  • BGFX_BUFFER_ALLOW_RESIZE - Buffer will resize on buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.

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

Returns:

Dynamic vertex buffer handle.

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

Create dynamic vertex buffer and initialize it.

Attention

C99’s equivalent binding is bgfx_create_dynamic_vertex_buffer_mem.

Parameters:

• _mem – [in] Vertex buffer data.

• _layout – [in] Vertex layout.

• _flags – [in] Buffer creation flags.

  • BGFX_BUFFER_NONE - No flags.

  • BGFX_BUFFER_COMPUTE_READ - Buffer will be read from by compute shader.

  • BGFX_BUFFER_COMPUTE_WRITE - Buffer will be written into by compute shader. When buffer is created with BGFX_BUFFER_COMPUTE_WRITE flag it cannot be updated from CPU.

  • BGFX_BUFFER_COMPUTE_READ_WRITE - Buffer will be used for read/write by compute shader.

  • BGFX_BUFFER_ALLOW_RESIZE - Buffer will resize on buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.

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

Returns:

Dynamic vertex buffer handle.

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

Update dynamic vertex buffer.

Attention

C99’s equivalent binding is bgfx_update_dynamic_vertex_buffer.

Parameters:

• _handle – [in] Dynamic vertex buffer handle.

• _startVertex – [in] Start vertex.

• _mem – [in] Vertex buffer data.

void bgfx::destroy(DynamicVertexBufferHandle _handle)

Destroy dynamic vertex buffer.

Attention

C99’s equivalent binding is bgfx_destroy_dynamic_vertex_buffer.

Parameters:

_handle – [in] Dynamic vertex buffer handle.

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

Returns number of requested or maximum available vertices.

Attention

C99’s equivalent binding is bgfx_get_avail_transient_vertex_buffer.

Parameters:

• _num – [in] Number of required vertices.

• _layout – [in] Vertex layout.

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

Allocate transient vertex buffer.

Attention

C99’s equivalent binding is bgfx_alloc_transient_vertex_buffer.

Parameters:

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

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

• _layout – [in] Vertex layout.

Index Buffers

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

Create static index buffer.

Attention

C99’s equivalent binding is bgfx_create_index_buffer.

Parameters:

• _mem – [in] Index buffer data.

• _flags – [in] Buffer creation flags.

  • BGFX_BUFFER_NONE - No flags.

  • BGFX_BUFFER_COMPUTE_READ - Buffer will be read from by compute shader.

  • BGFX_BUFFER_COMPUTE_WRITE - Buffer will be written into by compute shader. When buffer is created with BGFX_BUFFER_COMPUTE_WRITE flag it cannot be updated from CPU.

  • BGFX_BUFFER_COMPUTE_READ_WRITE - Buffer will be used for read/write by compute shader.

  • BGFX_BUFFER_ALLOW_RESIZE - Buffer will resize on buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.

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

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

Set static index buffer debug name.

Attention

C99’s equivalent binding is bgfx_set_index_buffer_name.

Parameters:

• _handle – [in] Static index buffer handle.

• _name – [in] Static index buffer name.

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

void bgfx::destroy(IndexBufferHandle _handle)

Destroy static index buffer.

Attention

C99’s equivalent binding is bgfx_destroy_index_buffer.

Parameters:

_handle – [in] Static index buffer handle.

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

Create empty dynamic index buffer.

Attention

C99’s equivalent binding is bgfx_create_dynamic_index_buffer.

Parameters:

• _num – [in] Number of indices.

• _flags – [in] Buffer creation flags.

  • BGFX_BUFFER_NONE - No flags.

  • BGFX_BUFFER_COMPUTE_READ - Buffer will be read from by compute shader.

  • BGFX_BUFFER_COMPUTE_WRITE - Buffer will be written into by compute shader. When buffer is created with BGFX_BUFFER_COMPUTE_WRITE flag it cannot be updated from CPU.

  • BGFX_BUFFER_COMPUTE_READ_WRITE - Buffer will be used for read/write by compute shader.

  • BGFX_BUFFER_ALLOW_RESIZE - Buffer will resize on buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.

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

Returns:

Dynamic index buffer handle.

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

Create a dynamic index buffer and initialize it.

Attention

C99’s equivalent binding is bgfx_create_dynamic_index_buffer_mem.

Parameters:

• _mem – [in] Index buffer data.

• _flags – [in] Buffer creation flags.

  • BGFX_BUFFER_NONE - No flags.

  • BGFX_BUFFER_COMPUTE_READ - Buffer will be read from by compute shader.

  • BGFX_BUFFER_COMPUTE_WRITE - Buffer will be written into by compute shader. When buffer is created with BGFX_BUFFER_COMPUTE_WRITE flag it cannot be updated from CPU.

  • BGFX_BUFFER_COMPUTE_READ_WRITE - Buffer will be used for read/write by compute shader.

  • BGFX_BUFFER_ALLOW_RESIZE - Buffer will resize on buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.

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

Returns:

Dynamic index buffer handle.

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

Update dynamic index buffer.

Attention

C99’s equivalent binding is bgfx_update_dynamic_index_buffer.

Parameters:

• _handle – [in] Dynamic index buffer handle.

• _startIndex – [in] Start index.

• _mem – [in] Index buffer data.

void bgfx::destroy(DynamicIndexBufferHandle _handle)

Destroy dynamic index buffer.

Attention

C99’s equivalent binding is bgfx_destroy_dynamic_index_buffer.

Parameters:

_handle – [in] Dynamic index buffer handle.

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

Returns number of requested or maximum available indices.

Attention

C99’s equivalent binding is bgfx_get_avail_transient_index_buffer.

Parameters:

• _num – [in] Number of required indices.

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

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

Allocate transient index buffer.

Attention

C99’s equivalent binding is bgfx_alloc_transient_index_buffer.

Parameters:

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

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

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

Textures

struct TextureFormat

Texture format enum.

Notation:

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

Attention

Availability depends on Caps (see: formats).

Attention

C99’s equivalent binding is bgfx_texture_format_t.

Public Types

enum Enum

Texture formats:

Values:

enumerator BC1

DXT1 R5G6B5A1.

enumerator BC2

DXT3 R5G6B5A4.

enumerator BC3

DXT5 R5G6B5A8.

enumerator BC4

LATC1/ATI1 R8.

enumerator BC5

LATC2/ATI2 RG8.

enumerator BC6H

BC6H RGB16F.

enumerator BC7

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

enumerator ETC1

ETC1 RGB8.

enumerator ETC2

ETC2 RGB8.

enumerator ETC2A

ETC2 RGBA8.

enumerator ETC2A1

ETC2 RGB8A1.

enumerator PTC12

PVRTC1 RGB 2BPP.

enumerator PTC14

PVRTC1 RGB 4BPP.

enumerator PTC12A

PVRTC1 RGBA 2BPP.

enumerator PTC14A

PVRTC1 RGBA 4BPP.

enumerator PTC22

PVRTC2 RGBA 2BPP.

enumerator PTC24

PVRTC2 RGBA 4BPP.

enumerator ATC

ATC RGB 4BPP.

enumerator ATCE

ATCE RGBA 8 BPP explicit alpha.

enumerator ATCI

ATCI RGBA 8 BPP interpolated alpha.

enumerator ASTC4x4

ASTC 4x4 8.0 BPP.

enumerator ASTC5x4

ASTC 5x4 6.40 BPP.

enumerator ASTC5x5

ASTC 5x5 5.12 BPP.

enumerator ASTC6x5

ASTC 6x5 4.27 BPP.

enumerator ASTC6x6

ASTC 6x6 3.56 BPP.

enumerator ASTC8x5

ASTC 8x5 3.20 BPP.

enumerator ASTC8x6

ASTC 8x6 2.67 BPP.

enumerator ASTC8x8

ASTC 8x8 2.00 BPP.

enumerator ASTC10x5

ASTC 10x5 2.56 BPP.

enumerator ASTC10x6

ASTC 10x6 2.13 BPP.

enumerator ASTC10x8

ASTC 10x8 1.60 BPP.

enumerator ASTC10x10

ASTC 10x10 1.28 BPP.

enumerator ASTC12x10

ASTC 12x10 1.07 BPP.

enumerator ASTC12x12

ASTC 12x12 0.89 BPP.

enumerator Unknown

enumerator R1

enumerator A8

enumerator R8

enumerator R8I

enumerator R8U

enumerator R8S

enumerator R16

enumerator R16I

enumerator R16U

enumerator R16F

enumerator R16S

enumerator R32I

enumerator R32U

enumerator R32F

enumerator RG8

enumerator RG8I

enumerator RG8U

enumerator RG8S

enumerator RG16

enumerator RG16I

enumerator RG16U

enumerator RG16F

enumerator RG16S

enumerator RG32I

enumerator RG32U

enumerator RG32F

enumerator RGB8

enumerator RGB8I

enumerator RGB8U

enumerator RGB8S

enumerator RGB9E5F

enumerator BGRA8

enumerator RGBA8

enumerator RGBA8I

enumerator RGBA8U

enumerator RGBA8S

enumerator RGBA16

enumerator RGBA16I

enumerator RGBA16U

enumerator RGBA16F

enumerator RGBA16S

enumerator RGBA32I

enumerator RGBA32U

enumerator RGBA32F

enumerator B5G6R5

enumerator R5G6B5

enumerator BGRA4

enumerator RGBA4

enumerator BGR5A1

enumerator RGB5A1

enumerator RGB10A2

enumerator RG11B10F

enumerator UnknownDepth

enumerator D16

enumerator D24

enumerator D24S8

enumerator D32

enumerator D16F

enumerator D24F

enumerator D32F

enumerator D0S8

enumerator Count

Texture Flags

BGFX_TEXTURE_MSAA_SAMPLE

Texture will be used for MSAA sampling.

BGFX_TEXTURE_RT

Render target no MSAA.

BGFX_TEXTURE_COMPUTE_WRITE

Texture will be used for compute write.

BGFX_TEXTURE_SRGB

Sample texture as sRGB.

BGFX_TEXTURE_BLIT_DST

Texture will be used as blit destination.

BGFX_TEXTURE_READ_BACK

Texture will be used for read back from GPU.

BGFX_TEXTURE_RT_MSAA_X2

Render target MSAAx2 mode.

BGFX_TEXTURE_RT_MSAA_X4

Render target MSAAx4 mode.

BGFX_TEXTURE_RT_MSAA_X8

Render target MSAAx8 mode.

BGFX_TEXTURE_RT_MSAA_X16

Render target MSAAx16 mode.

BGFX_TEXTURE_RT_WRITE_ONLY

Render target will be used for writing.

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

Validate texture parameters.

Attention

C99’s equivalent binding is bgfx_is_texture_valid.

Parameters:

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

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

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

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

• _flags – [in] Texture flags. See BGFX_TEXTURE_*.

Returns:

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

struct TextureInfo

Texture info.

Attention

C99’s equivalent binding is bgfx_texture_info_t.

Public Members

TextureFormat::Enum format

Texture format.

uint32_t storageSize

Total amount of bytes required to store texture.

uint16_t width

Texture width.

uint16_t height

Texture height.

uint16_t depth

Texture depth.

uint16_t numLayers

Number of layers in texture array.

uint8_t numMips

Number of MIP maps.

uint8_t bitsPerPixel

Format bits per pixel.

bool cubeMap

Texture is cubemap.

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

Calculate amount of memory required for texture.

Attention

C99’s equivalent binding is bgfx_calc_texture_size.

Parameters:

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

• _width – [in] Width.

• _height – [in] Height.

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

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

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

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

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

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

Create texture from memory buffer.

Attention

C99’s equivalent binding is bgfx_create_texture.

Parameters:

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

• _flags – [in] Texture creation (see BGFX_TEXTURE_*.), and sampler (see BGFX_SAMPLER_*) flags. Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.

  • BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

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

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

Returns:

Texture handle.

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

Create 2D texture.

Attention

C99’s equivalent binding is bgfx_create_texture_2d.

Parameters:

• _width – [in] Width.

• _height – [in] Height.

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

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

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

• _flags – [in] Texture creation (see BGFX_TEXTURE_*.), and sampler (see BGFX_SAMPLER_*) flags. Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.

  • BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

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

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

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

Attention

C99’s equivalent binding is bgfx_create_texture_2d_scaled.

Parameters:

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

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

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

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

• _flags – [in] Texture creation (see BGFX_TEXTURE_*.), and sampler (see BGFX_SAMPLER_*) flags. Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.

  • BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

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

Update 2D texture.

Attention

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

Attention

C99’s equivalent binding is bgfx_update_texture_2d.

Parameters:

• _handle – [in] Texture handle.

• _layer – [in] Layers in texture array.

• _mip – [in] Mip level.

• _x – [in] X offset in texture.

• _y – [in] Y offset in texture.

• _width – [in] Width of texture block.

• _height – [in] Height of texture block.

• _mem – [in] Texture update data.

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

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

Create 3D texture.

Attention

C99’s equivalent binding is bgfx_create_texture_3d.

Parameters:

• _width – [in] Width.

• _height – [in] Height.

• _depth – [in] Depth.

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

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

• _flags – [in] Texture creation (see BGFX_TEXTURE_*.), and sampler (see BGFX_SAMPLER_*) flags. Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.

  • BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

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

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

Update 3D texture.

Attention

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

Attention

C99’s equivalent binding is bgfx_update_texture_3d.

Parameters:

• _handle – [in] Texture handle.

• _mip – [in] Mip level.

• _x – [in] X offset in texture.

• _y – [in] Y offset in texture.

• _z – [in] Z offset in texture.

• _width – [in] Width of texture block.

• _height – [in] Height of texture block.

• _depth – [in] Depth of texture block.

• _mem – [in] Texture update data.

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

Create Cube texture.

Attention

C99’s equivalent binding is bgfx_create_texture_cube.

Parameters:

• _size – [in] Cube side size.

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

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

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

• _flags – [in] Texture creation (see BGFX_TEXTURE_*.), and sampler (see BGFX_SAMPLER_*) flags. Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.

  • BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

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

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

Update Cube texture.

Attention

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

Attention

C99’s equivalent binding is bgfx_update_texture_cube.

Parameters:

• _handle – [in] Texture handle.

• _layer – [in] Layers in texture array.

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

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

• _mip – [in] Mip level.

• _x – [in] X offset in texture.

• _y – [in] Y offset in texture.

• _width – [in] Width of texture block.

• _height – [in] Height of texture block.

• _mem – [in] Texture update data.

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

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

Read back texture content.

Attention

Texture must be created with BGFX_TEXTURE_READ_BACK flag.

Attention

Availability depends on: BGFX_CAPS_TEXTURE_READ_BACK.

Attention

C99’s equivalent binding is bgfx_read_texture.

Parameters:

• _handle – [in] Texture handle.

• _data – [in] Destination buffer.

• _mip – [in] Mip level.

Returns:

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

void *bgfx::getDirectAccessPtr(TextureHandle _handle)

Returns texture direct access pointer.

Attention

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

Attention

C99’s equivalent binding is bgfx_get_direct_access_ptr.

Parameters:

_handle – [in] Texture handle.

Returns:

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

void bgfx::destroy(TextureHandle _handle)

Destroy texture.

Attention

C99’s equivalent binding is bgfx_destroy_texture.

Parameters:

_handle – [in] Texture handle.

Frame Buffers

struct Attachment

Frame buffer texture attachment info.

Attention

C99’s equivalent binding is bgfx_attachment_t.

Public Functions

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

Init attachment.

Parameters:

• _handle – [in] Render target texture handle.

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

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

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

• _mip – [in] Mip level.

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

Public Members

Access::Enum access

Attachment access. See Access::Enum.

TextureHandle handle

Render target texture handle.

uint16_t mip

Mip level.

uint16_t layer

Cubemap side or depth layer/slice to use.

uint16_t numLayers

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

uint8_t resolve

Resolve flags. See: BGFX_RESOLVE_*

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

Validate frame buffer parameters.

Parameters:

• _num – [in] Number of attachments.

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

Returns:

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

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

Create frame buffer (simple).

Attention

C99’s equivalent binding is bgfx_create_frame_buffer.

Parameters:

• _width – [in] Texture width.

• _height – [in] Texture height.

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

• _textureFlags – [in] Texture creation (see BGFX_TEXTURE_*.), and sampler (see BGFX_SAMPLER_*) flags. Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.

  • BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

Returns:

Handle to frame buffer object.

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

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

Attention

C99’s equivalent binding is bgfx_create_frame_buffer_scaled.

Parameters:

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

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

• _textureFlags – [in] Texture creation (see BGFX_TEXTURE_*.), and sampler (see BGFX_SAMPLER_*) flags. Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.

  • BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

Returns:

Handle to frame buffer object.

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

Create MRT frame buffer from texture handles (simple).

Attention

C99’s equivalent binding is bgfx_create_frame_buffer_from_handles.

Parameters:

• _num – [in] Number of texture attachments.

• _handles – [in] Texture attachments.

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

Returns:

Handle to frame buffer object.

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

Create frame buffer for multiple window rendering.

Remark

Frame buffer cannot be used for sampling.

Attention

C99’s equivalent binding is bgfx_create_frame_buffer_from_nwh.

Parameters:

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

• _width – [in] Window back buffer width.

• _height – [in] Window back buffer height.

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

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

Returns:

Handle to frame buffer object.

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

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

Attention

C99’s equivalent binding is bgfx_create_frame_buffer_from_attachment.

Parameters:

• _num – [in] Number of texture attachments.

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

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

Returns:

Handle to frame buffer object.

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

Obtain texture handle of frame buffer attachment.

Attention

C99’s equivalent binding is bgfx_get_texture.

Parameters:

• _handle – [in] Frame buffer handle.

• _attachment – [in] Frame buffer attachment index.

Returns:

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

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

Set frame buffer debug name.

Attention

C99’s equivalent binding is bgfx_set_frame_buffer_name.

Parameters:

• _handle – [in] frame buffer handle.

• _name – [in] frame buffer name.

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

void bgfx::destroy(FrameBufferHandle _handle)

Destroy frame buffer.

Attention

C99’s equivalent binding is bgfx_destroy_frame_buffer.

Parameters:

_handle – [in] Frame buffer handle.

Instance Buffer

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

Returns number of requested or maximum available instance buffer slots.

Attention

C99’s equivalent binding is bgfx_get_avail_instance_data_buffer.

Parameters:

• _num – [in] Number of required instances.

• _stride – [in] Stride per instance.

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

Allocate instance data buffer.

Attention

C99’s equivalent binding is bgfx_alloc_instance_data_buffer.

Parameters:

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

• _num – [in] Number of instances.

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

Indirect Buffer

IndirectBufferHandle bgfx::createIndirectBuffer(uint32_t _num)

Create draw indirect buffer.

Attention

C99’s equivalent binding is bgfx_create_indirect_buffer.

Parameters:

_num – [in] Number of indirect calls.

Returns:

Indirect buffer handle.

void bgfx::destroy(IndirectBufferHandle _handle)

Destroy draw indirect buffer.

Attention

C99’s equivalent binding is bgfx_destroy_indirect_buffer.

Parameters:

_handle – [in] Indirect buffer handle.

Occlusion Query

OcclusionQueryHandle bgfx::createOcclusionQuery()

Create occlusion query.

Attention

C99’s equivalent binding is bgfx_create_occlusion_query.

Returns:

Handle to occlusion query object.

struct OcclusionQueryResult

Occlusion query result.

Attention

C99’s equivalent binding is bgfx_occlusion_query_result_t.

Public Types

enum Enum

Occlusion query results:

Values:

enumerator Invisible

Query failed test.

enumerator Visible

Query passed test.

enumerator NoResult

Query result is not available yet.

enumerator Count

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

Retrieve occlusion query result from previous frame.

Attention

C99’s equivalent binding is bgfx_get_result.

Parameters:

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

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

Returns:

Occlusion query result.

void bgfx::destroy(OcclusionQueryHandle _handle)

Destroy occlusion query.

Attention

C99’s equivalent binding is bgfx_destroy_occlusion_query.

Parameters:

_handle – [in] Handle to occlusion query object.