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:

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 transientVbSize¶: Maximum transient vertex buffer size.

uint32_t transientIbSize¶: Maximum transient index buffer size.

struct Resolution¶

Backbuffer resolution and reset parameters.

Attention: C99’s equivalent binding is bgfx_resolution_t.

Public Members

TextureFormat::Enum format¶: Backbuffer 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, _y – [in] 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, _y – [in] 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, _y – [in] 2D position from top-left.
_width, _height – [in] Image width and 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 transientVbSize¶: Maximum transient vertex buffer size.

uint32_t transientIbSize¶: Maximum transient index 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. All texture compare modes are 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.

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

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.

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 trinagle 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, _g, _b, _a – [in] 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¶

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

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

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

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

Warning

doxygenfunction: Unable to resolve function “bgfx::submit” with arguments (ViewId, ProgramHandle, IndirectBufferHandle, uint16_t, uint16_t, uint32_t, uint8_t) in doxygen xml output for project “bgfx” from directory: ../../.build/docs/xml. Potential matches:

- 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)
- 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)
- void submit(ViewId _id, ProgramHandle _program, OcclusionQueryHandle _occlusionQuery, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)
- void submit(ViewId _id, ProgramHandle _program, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)

Warning

doxygenfunction: Unable to resolve function “bgfx::submit” with arguments (ViewId, ProgramHandle, IndirectBufferHandle, uint16_t, IndexBufferHandle, uint32_t, uint16_t, uint32_t, uint8_t) in doxygen xml output for project “bgfx” from directory: ../../.build/docs/xml. Potential matches:

- 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)
- 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)
- void submit(ViewId _id, ProgramHandle _program, OcclusionQueryHandle _occlusionQuery, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)
- void submit(ViewId _id, ProgramHandle _program, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)

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

Warning

doxygenfunction: Unable to resolve function “bgfx::dispatch” with arguments (ViewId, ProgramHandle, IndirectBufferHandle, uint16_t, uint16_t, uint8_t) in doxygen xml output for project “bgfx” from directory: ../../.build/docs/xml. Potential matches:

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

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.

Remark

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.
Predefined uniforms (declared in bgfx_shader.sh):
- u_viewRect vec4(x, y, width, height) - view rectangle for current view, in pixels.
- u_viewTexel vec4(1.0/width, 1.0/height, undef, undef) - inverse width and height
- u_view mat4 - view matrix
- u_invView mat4 - inverted view matrix
- u_proj mat4 - projection matrix
- u_invProj mat4 - inverted projection matrix
- u_viewProj mat4 - concatenated view projection matrix
- u_invViewProj mat4 - concatenated inverted view projection matrix
- u_model mat4[BGFX_CONFIG_MAX_BONES] - array of model matrices.
- u_modelView mat4 - concatenated model view matrix, only first model matrix from array is used.
- u_modelViewProj mat4 - concatenated model view projection matrix.
- u_alphaRef float - alpha reference value for alpha test.

Attention: C99’s equivalent binding is bgfx_create_uniform.

Parameters:

_name – [in] Uniform name in shader.
_type – [in] Type of uniform (See: bgfx::UniformType).
_num – [in] Number of elements in array.

Returns:

Handle to uniform object.

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¶

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