API Reference

General

Initialization and Shutdown

bool bgfx::init(RendererType::Enum _type = RendererType::Count, uint16_t _vendorId = BGFX_PCI_ID_NONE, uint16_t _deviceId = 0, CallbackI *_callback = NULL, bx::AllocatorI *_allocator = NULL)

Initialize bgfx library.

Return

true if initialization was successful.

Attention

C99 equivalent is bgfx_init.

Parameters

• _type -

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

• _vendorId -

  Vendor PCI id. If set to BGFX_PCI_ID_NONE it will select the first device.

  • BGFX_PCI_ID_NONE - Autoselect adapter.
  • BGFX_PCI_ID_SOFTWARE_RASTERIZER - Software rasterizer.
  • BGFX_PCI_ID_AMD - AMD adapter.
  • BGFX_PCI_ID_INTEL - Intel adapter.
  • BGFX_PCI_ID_NVIDIA - nVidia adapter.

• _deviceId -

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

• _callback -

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

• _allocator -

  Custom allocator. When custom allocator is not specified, library uses default CRT allocator. The library assumes custom allocator is thread safe.

BGFX_PCI_ID_NONE

Autoselect adapter.

BGFX_PCI_ID_SOFTWARE_RASTERIZER

Software rasterizer.

BGFX_PCI_ID_AMD

AMD adapter.

BGFX_PCI_ID_INTEL

Intel adapter.

BGFX_PCI_ID_NVIDIA

nVidia adapter.

struct bgfx::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 equivalent is bgfx_callback_interface_t.

Public Functions

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

If fatal code code is not Fatal::DebugCheck this callback is called on unrecoverable error. It’s not safe to continue, inform user and terminate application from this call.

Remark

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

Attention

C99 equivalent is bgfx_callback_vtbl.fatal.

Parameters

• _code -

  Fatal error code.

• _str -

  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 equivalent is bgfx_callback_vtbl.trace_vargs.

Parameters

• _filePath -

  File path where debug message was generated.

• _line -

  Line where debug message was generated.

• _format -

  printf style format.

• _argList -

  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 equivalent is bgfx_callback_vtbl.profiler_begin.

Parameters

• _name -

  Region name, contains dynamic string.

• _abgr -

  Color of profiler region.

• _filePath -

  File path where profilerBegin was called.

• _line -

  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 equivalent is bgfx_callback_vtbl.profiler_begin_literal.

Parameters

• _name -

  Region name, contains string literal.

• _abgr -

  Color of profiler region.

• _filePath -

  File path where profilerBeginLiteral was called.

• _line -

  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 equivalent is bgfx_callback_vtbl.profiler_end.

virtual uint32_t cacheReadSize(uint64_t _id) = 0

Return size of for cached item. Return 0 if no cached item was found.

Return

Number of bytes to read.

Attention

C99 equivalent is bgfx_callback_vtbl.cache_read_size.

Parameters

• _id -

  Cache id.

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

Read cached item.

Return

True if data is read.

Attention

C99 equivalent is bgfx_callback_vtbl.cache_read.

Parameters

• _id -

  Cache id.

• _data -

  Buffer where to read data.

• _size -

  Size of data to read.

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

Write cached item.

Attention

C99 equivalent is bgfx_callback_vtbl.cache_write.

Parameters

• _id -

  Cache id.

• _data -

  Data to write.

• _size -

  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 equivalent is bgfx_callback_vtbl.screen_shot.

Parameters

• _filePath -

  File path.

• _width -

  Image width.

• _height -

  Image height.

• _pitch -

  Number of bytes to skip to next line.

• _data -

  Image data.

• _size -

  Image size.

• _yflip -

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

Attention

C99 equivalent is bgfx_callback_vtbl.capture_begin.

virtual void captureEnd() = 0

Called when capture ends.

Attention

C99 equivalent is bgfx_callback_vtbl.capture_end.

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

Captured frame.

Attention

C99 equivalent is bgfx_callback_vtbl.capture_frame.

Parameters

• _data -

  Image data.

• _size -

  Image size.

void bgfx::shutdown()

Shutdown bgfx library.

Attention

C99 equivalent is bgfx_shutdown.

Updating

Reset

void bgfx::reset(uint32_t _width, uint32_t _height, uint32_t _flags = BGFX_RESET_NONE)

Reset graphic settings and back-buffer size.

Attention

This call doesn’t actually change window size, it just resizes back-buffer. Windowing code has to change window size.

Attention

C99 equivalent is bgfx_reset.

Parameters

• _width -

  Back-buffer width.

• _height -

  Back-buffer height.

• _flags -

  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_HMD - HMD stereo rendering.
  • BGFX_RESET_HMD_DEBUG - HMD stereo rendering debug mode.
  • BGFX_RESET_HMD_RECENTER - HMD calibration.
  • 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 backbuffer.

BGFX_RESET_NONE

No reset flags.

BGFX_RESET_FULLSCREEN

Not supported yet.

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_VSYNC

Enable V-Sync.

BGFX_RESET_MAXANISOTROPY

Turn on/off max anisotropy.

BGFX_RESET_CAPTURE

Begin screen capture.

BGFX_RESET_HMD

HMD stereo rendering.

BGFX_RESET_HMD_DEBUG

HMD stereo rendering debug mode.

BGFX_RESET_HMD_RECENTER

HMD calibration.

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

BGFX_RESET_HIDPI

Enable HiDPI rendering.

BGFX_RESET_DEPTH_CLAMP

Enable depth clamp.

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.

Return

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.

Attention

C99 equivalent is bgfx_frame.

Parameters

• _capture -

  Capture frame with graphics debugger.

Debug

Debug Features

void bgfx::setDebug(uint32_t _debug)

Set debug flags.

Attention

C99 equivalent is bgfx_set_debug.

Parameters

• _debug -

  Available flags:

  • BGFX_DEBUG_IFH - Infinitely fast hardware. When this flag is set all rendering calls will be skipped. It’s useful when profiling to quickly assess bottleneck between CPU and GPU.
  • BGFX_DEBUG_PROFILER - Enabled 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.

Debug Text Display

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

Clear internal debug text buffer.

Attention

C99 equivalent is bgfx_dbg_text_clear.

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 equivalent is bgfx_dbg_text_printf.

Parameters

• _x_y -

  2D position from top-left.

• _attr -

  Color palette. Where top 4-bits represent index of background, and bottom 4-bits represent foreground color from standard VGA text palette.

• _format -

  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 equivalent is bgfx_dbg_text_vprintf.

Parameters

• _x_y -

  2D position from top-left.

• _attr -

  Color palette. Where top 4-bits represent index of background, and bottom 4-bits represent foreground color from standard VGA text palette.

• _format -

  printf style format.

• _argList -

  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 equivalent is bgfx_dbg_text_image.

Parameters

• _x_y -

  2D position from top-left.

• _width_height -

  Image width and height.

• _data -

  Raw image data (character/attribute raw encoding).

• _pitch -

  Image pitch in bytes.

Querying information

Renderer

RendererType::Enum bgfx::getRendererType()

Returns current renderer backend API type.

Remark

Library must be initialized.

Attention

C99 equivalent is bgfx_get_renderer_type.

struct bgfx::RendererType

Renderer backend type enum.

Attention

C99 equivalent is bgfx_renderer_type_t.

Public Types

enum Enum

Renderer types:

Values:

Noop

No rendering.

Direct3D9

Direct3D 9.0.

Direct3D11

Direct3D 11.0.

Direct3D12

Direct3D 12.0.

Gnm

GNM.

Metal

Metal.

OpenGLES

OpenGL ES 2.0+.

OpenGL

OpenGL 2.1+.

Vulkan

Vulkan.

Count

Capabilities

const Caps *bgfx::getCaps()

Returns renderer capabilities.

Return

Pointer to static bgfx::Caps structure.

Remark

Library must be initialized.

Attention

C99 equivalent is bgfx_get_caps.

struct bgfx::Caps

Renderer capabilities.

Attention

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

bool originBottomLeft

True when NDC origin is at bottom left.

uint8_t numGPUs

Number of enumerated GPUs.

GPU gpu[4]

Enumerated GPUs.

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 - Texture format can be used as image from compute shader.
• 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 equivalent is bgfx_caps_gpu_t.

Public Members

uint16_t vendorId

Vendor PCI id. See BGFX_PCI_ID_*.

uint16_t deviceId

Device id.

struct Limits

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

Maximum number of vertex format declarations.

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.

Available Caps

BGFX_CAPS_TEXTURE_COMPARE_LEQUAL

Texture compare less equal mode is supported.

BGFX_CAPS_TEXTURE_COMPARE_ALL

All texture compare modes are supported.

BGFX_CAPS_TEXTURE_3D

3D textures are supported.

BGFX_CAPS_VERTEX_ATTRIB_HALF

Vertex attribute half-float is supported.

BGFX_CAPS_INSTANCING

Instancing is supported.

BGFX_CAPS_RENDERER_MULTITHREADED

Renderer is on separate thread.

BGFX_CAPS_FRAGMENT_DEPTH

Fragment depth is accessible in fragment shader.

BGFX_CAPS_BLEND_INDEPENDENT

Blend independent is supported.

BGFX_CAPS_COMPUTE

Compute shaders are supported.

BGFX_CAPS_FRAGMENT_ORDERING

Fragment ordering is available in fragment shader.

BGFX_CAPS_SWAP_CHAIN

Multiple windows are supported.

BGFX_CAPS_HMD

Head Mounted Display is available.

BGFX_CAPS_INDEX32

32-bit indices are supported.

BGFX_CAPS_DRAW_INDIRECT

Draw indirect is supported.

BGFX_CAPS_HIDPI

HiDPI rendering is supported.

BGFX_CAPS_TEXTURE_BLIT

Texture blit is supported.

BGFX_CAPS_TEXTURE_READ_BACK

Read-back texture is supported.

BGFX_CAPS_OCCLUSION_QUERY

Occlusion query is supported.

Statistics

const Stats *bgfx::getStats()

Returns performance counters.

Attention

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

Attention

C99 equivalent is bgfx_get_stats.

struct bgfx::Stats

Renderer statistics data.

Attention

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

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 maxGpuLatency

GPU driver latency.

int64_t gpuMemoryMax

Maximum available GPU memory for application.

int64_t gpuMemoryUsed

Amount of GPU memory used.

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

View stats.

uint8_t numEncoders

Number of encoders used during frame.

EncoderStats *encoderStats

Encoder stats.

Head Mounted Display

const HMD *bgfx::getHMD()

Returns HMD info.

Attention

C99 equivalent is bgfx_get_hmd.

struct bgfx::HMD

HMD info.

Attention

C99 equivalent is bgfx_hmd_t.

Public Members

uint16_t width

Frame buffer width.

uint16_t height

Frame buffer height.

uint32_t deviceWidth

Device resolution width.

uint32_t deviceHeight

Device resolution height.

uint8_t flags

Status flags.

struct Eye

Eye.

Attention

C99 equivalent is bgfx_hmd_eye_t.

Public Members

float rotation[4]

Eye rotation represented as quaternion.

float translation[3]

Eye translation.

float fov[4]

Field of view (up, down, left, right).

float viewOffset[3]

Eye view matrix translation adjustment.

float projection[16]

Eye projection matrix.

float pixelsPerTanAngle[2]

Number of pixels that fit in tan(angle) = 1.

BGFX_HMD_NONE

None.

BGFX_HMD_DEVICE_RESOLUTION

Has HMD native resolution.

BGFX_HMD_RENDERING

Rendering to HMD.

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.

Return

Current renderer state. See: bgfx::RenderFrame.

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.

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.

struct bgfx::RenderFrame

Render frame enum.

Attention

C99 equivalent is bgfx_render_frame_t.

void bgfx::setPlatformData(const PlatformData &_data)

Set platform data.

Warning

Must be called before bgfx::init.

Attention

C99 equivalent is bgfx_set_platform_data.

struct bgfx::PlatformData

Platform data.

Attention

C99 equivalent is bgfx_platform_data_t.

Public Members

void *ndt

Native display type.

void *nwh

Native window handle.

void *context

GL context, or D3D device.

void *backBuffer

GL backbuffer, or D3D render target view.

void *backBufferDS

Backbuffer depth/stencil.

void *session

ovrSession, for Oculus SDK

const InternalData *bgfx::getInternalData()

Get internal data for interop.

Attention

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

Warning

Must be called only on render thread.

Attention

C99 equivalent is bgfx_get_internal_data.

struct bgfx::InternalData

Internal data.

Attention

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

Return

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

Warning

Must be called only on render thread.

Attention

C99 equivalent is bgfx_override_internal_texture_ptr.

Parameters

• _handle -

  Texture handle.

• _ptr -

  Native API pointer to texture.

uintptr_t bgfx::overrideInternal(TextureHandle _handle, uint16_t _width, uint16_t _height, uint8_t _numMips, TextureFormat::Enum _format, uint32_t _flags = BGFX_TEXTURE_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.

Return

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

Warning

Must be called only on render thread.

Attention

C99 equivalent is bgfx_override_internal_texture.

Parameters

• _handle -

  Texture handle.

• _width -

  Width.

• _height -

  Height.

• _numMips -

  Number of mip-maps.

• _format -

  Texture format. See: TextureFormat::Enum.

• _flags -

  Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_TEXTURE_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.
  • BGFX_TEXTURE_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

Miscellaneous

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

Pack vertex attribute into vertex stream format.

Attention

C99 equivalent is bgfx_vertex_pack.

Parameters

• _input -

  Value to be packed into vertex stream.

• _inputNormalized -

  True if input value is already normalized.

• _attr -

  Attribute to pack.

• _decl -

  Vertex stream declaration.

• _data -

  Destination vertex stream where data will be packed.

• _index -

  Vertex index that will be modified.

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

Unpack vertex attribute from vertex stream format.

Attention

C99 equivalent is bgfx_vertex_unpack.

Parameters

• _output -

  Result of unpacking.

• _attr -

  Attribute to unpack.

• _decl -

  Vertex stream declaration.

• _data -

  Source vertex stream from where data will be unpacked.

• _index -

  Vertex index that will be unpacked.

void bgfx::vertexConvert(const VertexDecl &_destDecl, void *_destData, const VertexDecl &_srcDecl, const void *_srcData, uint32_t _num = 1)

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

Attention

C99 equivalent is bgfx_vertex_convert.

Parameters

• _destDecl -

  Destination vertex stream declaration.

• _destData -

  Destination vertex stream.

• _srcDecl -

  Source vertex stream declaration.

• _srcData -

  Source vertex stream data.

• _num -

  Number of vertices to convert from source to destination.

uint16_t bgfx::weldVertices(uint16_t *_output, const VertexDecl &_decl, const void *_data, uint16_t _num, float _epsilon = 0.001f)

Weld vertices.

Return

Number of unique vertices after vertex welding.

Attention

C99 equivalent is bgfx_weld_vertices.

Parameters

• _output -

  Welded vertices remapping table. The size of buffer must be the same as number of vertices.

• _decl -

  Vertex stream declaration.

• _data -

  Vertex stream.

• _num -

  Number of vertices in vertex stream.

• _epsilon -

  Error tolerance for vertex position comparison.

struct bgfx::TopologyConvert

Topology conversion function.

Attention

C99 equivalent is bgfx_topology_convert_t.

Public Types

enum Enum

Topology conversion functions:

Values:

TriListFlipWinding

Flip winding order of triangle list.

TriListToLineList

Convert triangle list to line list.

TriStripToTriList

Convert triangle strip to triangle list.

LineStripToLineList

Convert line strip to line list.

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.

Return

Number of output indices after conversion.

Attention

C99 equivalent is bgfx_topology_convert.

Parameters

• _conversion -

  Conversion type, see TopologyConvert::Enum.

• _dst -

  Destination index buffer. If this argument is NULL function will return number of indices after conversion.

• _dstSize -

  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 -

  Source indices.

• _numIndices -

  Number of input indices.

• _index32 -

  Set to true if input indices are 32-bit.

struct bgfx::TopologySort

Topology sort order.

Attention

C99 equivalent is bgfx_topology_sort_t.

Public Types

enum Enum

Topology sort order:

Values:

DirectionFrontToBackMin

DirectionFrontToBackAvg

DirectionFrontToBackMax

DirectionBackToFrontMin

DirectionBackToFrontAvg

DirectionBackToFrontMax

DistanceFrontToBackMin

DistanceFrontToBackAvg

DistanceFrontToBackMax

DistanceBackToFrontMin

DistanceBackToFrontAvg

DistanceBackToFrontMax

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 equivalent is bgfx_topology_sort_tri_list.

Parameters

• _sort -

  Sort order, see TopologySort::Enum.

• _dst -

  Destination index buffer.

• _dstSize -

  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 -

  Direction (vector must be normalized).

• _pos -

  Position.

• _vertices -

  Pointer to first vertex represented as float x, y, z. Must contain at least number of vertices referencende by index buffer.

• _stride -

  Vertex stride.

• _indices -

  Source indices.

• _numIndices -

  Number of input indices.

• _index32 -

  Set to true if input indices are 32-bit.

void bgfx::discard()

Discard all previously set state for draw or compute call.

Attention

C99 equivalent is bgfx_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.

Parameters

• _id -

  View id.

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

Set palette color value.

Attention

C99 equivalent is bgfx_set_palette_color.

Parameters

• _index -

  Index into palette.

• _rgba -

  Packed 32-bit RGBA value.

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

Set palette color value.

Attention

C99 equivalent is bgfx_set_palette_color.

Parameters

• _index -

  Index into palette.

• _rgba -

  RGBA floating point value.

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

Set palette color value.

Attention

C99 equivalent is bgfx_set_palette_color.

Parameters

• _index -

  Index into palette.

• _r_g_b_a -

  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 equivalent is bgfx_request_screen_shot.

Parameters

• _handle -

  Frame buffer handle. If handle is BGFX_INVALID_HANDLE request will be made for main window back buffer.

• _filePath -

  Will be passed to bgfx::CallbackI::screenShot callback.

Views

View is primary sorting mechanism in bgfx. View represent bucket of draw and compute calls. Compute and draw calls inside bucket are sorted in the way that all compute calls are executed before draw calls. Compute calls are always in order of submission, while draw calls are sorted by internal state if view is not in sequential mode. In the most of cases when z-buffer is used this change in order is not noticable to desired output. In cases where order has to be preserved (for example in rendering GUIs), view can be set to be in sequential order. Sequential order is less efficient, because it doesn’t allow state change optimization, and should be avoided when possible.

By default views ids are sorted in ascending order. For dynamic renderers where order might not be known until the last moment, view ids can be remaped to arbitrary order by calling bgfx::setViewOrder.

View state is preserved between multiple frames.

void bgfx::setViewName(ViewId _id, const char *_name)

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.

Parameters

• _id -

  View id.

• _name -

  View name.

Attention

C99 equivalent is bgfx_set_view_name.

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 equivalent is bgfx_set_view_rect.

Parameters

• _id -

  View id.

• _x -

  Position x from the left corner of the window.

• _y -

  Position y from the top corner of the window.

• _width -

  Width of view port region.

• _height -

  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 equivalent is bgfx_set_view_rect_auto.

Parameters

• _id -

  View id.

• _x -

  Position x from the left corner of the window.

• _y -

  Position y from the top corner of the window.

• _ratio -

  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 equivalent is bgfx_set_view_scissor.

Parameters

• _id -

  View id.

• _x -

  Position x from the left corner of the window.

• _y -

  Position y from the top corner of the window.

• _width -

  Width of scissor region.

• _height -

  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 equivalent is bgfx_set_view_clear.

Parameters

• _id -

  View id.

• _flags -

  Clear flags. Use BGFX_CLEAR_NONE to remove any clear operation. See: BGFX_CLEAR_*.

• _rgba -

  Color clear value.

• _depth -

  Depth clear value.

• _stencil -

  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. Must use setClearColor to setup clear color palette.

Attention

C99 equivalent is bgfx_set_view_clear_mrt.

Parameters

• _id -

  View id.

• _flags -

  Clear flags. Use BGFX_CLEAR_NONE to remove any clear operation. See: BGFX_CLEAR_*.

• _depth -

  Depth clear value.

• _stencil -

  Stencil clear value.

• _0 -

  Palette index for frame buffer attachment 0.

• _1 -

  Palette index for frame buffer attachment 1.

• _2 -

  Palette index for frame buffer attachment 2.

• _3 -

  Palette index for frame buffer attachment 3.

• _4 -

  Palette index for frame buffer attachment 4.

• _5 -

  Palette index for frame buffer attachment 5.

• _6 -

  Palette index for frame buffer attachment 6.

• _7 -

  Palette index for frame buffer attachment 7.

struct bgfx::ViewMode

View mode sets draw call sort order.

Attention

C99 equivalent is bgfx_view_mode_t.

Public Types

enum Enum

View modes:

Values:

Default

Default sort order.

Sequential

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

DepthAscending

Sort draw call depth in ascending order.

DepthDescending

Sort draw call depth in descending order.

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 equivalent is bgfx_set_view_mode.

Parameters

• _id -

  View id.

• _mode -

  View sort mode. See ViewMode::Enum.

void bgfx::setViewTransform(ViewId _id, const void *_view, const void *_projL, uint8_t _flags = BGFX_VIEW_STEREO, const void *_projR = NULL)

Set view view and projection matrices, all draw primitives in this view will use these matrices.

Attention

C99 equivalent are bgfx_set_view_transform, bgfx_set_view_transform_stereo.

Parameters

• _id -

  View id.

• _view -

  View matrix.

• _projL -

  Projection matrix. When using stereo rendering this projection matrix represent projection matrix for left eye.

• _flags -

  View flags. Use

  • BGFX_VIEW_NONE - View will be rendered only once if stereo mode is enabled.
  • BGFX_VIEW_STEREO - View will be rendered for both eyes if stereo mode is enabled. When stereo mode is disabled this flag doesn’t have effect.

• _projR -

  Projection matrix for right eye in stereo mode.

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

Post submit view reordering.

Attention

C99 equivalent is bgfx_set_view_order.

Parameters

• _id -

  First view id.

• _num -

  Number of views to remap.

• _remap -

  View remap id table. Passing NULL will reset view ids to default state.

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

Set view frame buffer.

Remark

Not persistent after bgfx::reset call.

Attention

C99 equivalent is bgfx_set_view_frame_buffer.

Parameters

• _id -

  View id.

• _handle -

  Frame buffer handle. Passing BGFX_INVALID_HANDLE as frame buffer handle will draw primitives from this view into default back buffer.

Encoder

Encoder

API for multi-threaded submission.

Encoder *bgfx::begin()

Begin submitting draw calls from thread.

void bgfx::end(Encoder *_encoder)

End submitting draw calls from thread.

struct bgfx::Encoder

Encoder for submitting draw calls from multiple threads. Use bgfx::begin() to obtain encoder for thread.

Attention

C99 equivalent is bgfx_encoder.

Public Functions

void setMarker(const char *_marker)

Sets debug marker.

Attention

C99 equivalent is bgfx_set_marker.

void setState(uint64_t _state, uint32_t _rgba = 0)

Set render states for draw primitive.

Remark

1. To setup more complex states use: BGFX_STATE_ALPHA_REF(_ref), BGFX_STATE_POINT_SIZE(_size), BGFX_STATE_BLEND_FUNC(_src, _dst), BGFX_STATE_BLEND_FUNC_SEPARATE(_srcRGB, _dstRGB, _srcA, _dstA) BGFX_STATE_BLEND_EQUATION(_equation) BGFX_STATE_BLEND_EQUATION_SEPARATE(_equationRGB, _equationA)
2. BGFX_STATE_BLEND_EQUATION_ADD is set when no other blend equation is specified.

Attention

C99 equivalent is bgfx_set_state.

Parameters

• _state -

  State flags. Default state for primitive type is triangles. See: BGFX_STATE_DEFAULT.

  • BGFX_STATE_ALPHA_WRITE - Enable alpha write.
  • BGFX_STATE_DEPTH_WRITE - Enable depth write.
  • 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_RGB_WRITE - Enable RGB write.
  • BGFX_STATE_MSAA - Enable MSAA.
  • BGFX_STATE_PT_[TRISTRIP/LINES/POINTS] - Primitive type.

• _rgba -

  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 equivalent is bgfx_set_condition.

Parameters

• _handle -

  Occlusion query handle.

• _visible -

  Render if occlusion query is visible.

void setStencil(uint32_t _fstencil, uint32_t _bstencil = BGFX_STENCIL_NONE)

Set stencil test state.

Attention

C99 equivalent is bgfx_set_stencil.

Parameters

• _fstencil -

  Front stencil state.

• _bstencil -

  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. For scissor for all primitives in view see bgfx::setViewScissor.

Return

Scissor cache index.

Attention

C99 equivalent is bgfx_set_scissor.

Parameters

• _x -

  Position x from the left corner of the window.

• _y -

  Position y from the top corner of the window.

• _width -

  Width of scissor region.

• _height -

  Height of scissor region.

void setScissor(uint16_t _cache = UINT16_MAX)

Set scissor from cache for draw primitive.

Attention

C99 equivalent is bgfx_set_scissor_cached.

Parameters

• _cache -

  Index in scissor cache. Passing UINT16_MAX unset primitive scissor and primitive will 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.

Return

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

Attention

C99 equivalent is bgfx_set_transform.

Parameters

• _mtx -

  Pointer to first matrix in array.

• _num -

  Number of matrices in array.

uint32_t allocTransform(Transform *_transform, uint16_t _num)

Reserve _num matrices in internal matrix cache.

Return

index into matrix cache.

Attention

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

Attention

C99 equivalent is bgfx_alloc_transform.

Parameters

• _transform -

  Pointer to Transform structure.

• _num -

  Number of matrices.

void setTransform(uint32_t _cache, uint16_t _num = 1)

Set model matrix from matrix cache for draw primitive.

Attention

C99 equivalent is bgfx_set_transform_cached.

Parameters

• _cache -

  Index in matrix cache.

• _num -

  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 equivalent is bgfx_set_uniform.

Parameters

• _handle -

  Uniform.

• _value -

  Pointer to uniform data.

• _num -

  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 equivalent is bgfx_set_index_buffer.

Parameters

• _handle -

  Index buffer.

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

Set index buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_index_buffer.

Parameters

• _handle -

  Index buffer.

• _firstIndex -

  First index to render.

• _numIndices -

  Number of indices to render.

void setIndexBuffer(DynamicIndexBufferHandle _handle)

Set index buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_dynamic_index_buffer.

Parameters

• _handle -

  Dynamic index buffer.

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

Set index buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_dynamic_index_buffer.

Parameters

• _handle -

  Dynamic index buffer.

• _firstIndex -

  First index to render.

• _numIndices -

  Number of indices to render.

void setIndexBuffer(const TransientIndexBuffer *_tib)

Set index buffer for draw primitive.

Remark

_tib pointer after this call is invalid.

Attention

C99 equivalent is bgfx_set_transient_index_buffer.

Parameters

• _tib -

  Transient index buffer.

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

Set index buffer for draw primitive.

Remark

_tib pointer after this call is invalid.

Attention

C99 equivalent is bgfx_set_transient_index_buffer.

Parameters

• _tib -

  Transient index buffer.

• _firstIndex -

  First index to render.

• _numIndices -

  Number of indices to render.

void setVertexBuffer(uint8_t _stream, VertexBufferHandle _handle)

Set vertex buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_vertex_buffer.

Parameters

• _stream -

  Vertex stream.

• _handle -

  Vertex buffer.

void setVertexBuffer(uint8_t _stream, VertexBufferHandle _handle, uint32_t _startVertex, uint32_t _numVertices)

Set vertex buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_vertex_buffer.

Parameters

• _stream -

  Vertex stream.

• _handle -

  Vertex buffer.

• _startVertex -

  First vertex to render.

• _numVertices -

  Number of vertices to render.

void setVertexBuffer(uint8_t _stream, DynamicVertexBufferHandle _handle)

Set vertex buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_dynamic_vertex_buffer.

Parameters

• _stream -

  Vertex stream.

• _handle -

  Dynamic vertex buffer.

void setVertexBuffer(uint8_t _stream, DynamicVertexBufferHandle _handle, uint32_t _startVertex, uint32_t _numVertices)

Set vertex buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_dynamic_vertex_buffer.

Parameters

• _stream -

  Vertex stream.

• _handle -

  Dynamic vertex buffer.

• _startVertex -

  First vertex to render.

• _numVertices -

  Number of vertices to render.

void setVertexBuffer(uint8_t _stream, const TransientVertexBuffer *_tvb)

Set vertex buffer for draw primitive.

Remark

_tvb pointer after this call is invalid.

Attention

C99 equivalent is bgfx_set_transient_vertex_buffer.

Parameters

• _stream -

  Vertex stream.

• _tvb -

  Transient vertex buffer.

void setVertexBuffer(uint8_t _stream, const TransientVertexBuffer *_tvb, uint32_t _startVertex, uint32_t _numVertices)

Set vertex buffer for draw primitive.

Remark

_tvb pointer after this call is invalid.

Attention

C99 equivalent is bgfx_set_transient_vertex_buffer.

Parameters

• _stream -

  Vertex stream.

• _tvb -

  Transient vertex buffer.

• _startVertex -

  First vertex to render.

• _numVertices -

  Number of vertices to render.

void setInstanceDataBuffer(const InstanceDataBuffer *_idb, uint32_t _num = UINT32_MAX)

Set instance data buffer for draw primitive.

Remark

_idb pointer after this call is invalid.

Attention

C99 equivalent is bgfx_set_instance_data_buffer.

Parameters

• _idb -

  Transient instance data buffer.

• _num -

  Number of data instances.

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

Set instance data buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_instance_data_from_vertex_buffer.

Parameters

• _handle -

  Vertex buffer.

• _start -

  First instance data.

• _num -

  Number of data instances.

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

Set instance data buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_instance_data_from_dynamic_vertex_buffer.

Parameters

• _handle -

  Vertex buffer.

• _start -

  First instance data.

• _num -

  Number of data instances.

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

Set texture stage for draw primitive.

Attention

C99 equivalent is bgfx_set_texture.

Parameters

• _stage -

  Texture unit.

• _sampler -

  Program sampler.

• _handle -

  Texture handle.

• _flags -

  Texture sampling mode. Default value UINT32_MAX uses texture sampling settings from the texture.

  • BGFX_TEXTURE_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.
  • BGFX_TEXTURE_[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.

These empty draw calls will sort before ordinary draw calls.

Parameters

• _id -

  View id.

void submit(ViewId _id, ProgramHandle _program, int32_t _depth = 0, bool _preserveState = false)

Submit primitive for rendering.

Attention

C99 equivalent is bgfx_submit.

Parameters

• _id -

  View id.

• _program -

  Program.

• _depth -

  Depth for sorting.

• _preserveState -

  Preserve internal draw state for next draw call submit.

void submit(ViewId _id, ProgramHandle _program, OcclusionQueryHandle _occlusionQuery, int32_t _depth = 0, bool _preserveState = false)

Submit primitive with occlusion query for rendering.

Attention

C99 equivalent is bgfx_submit_occlusion_query.

Parameters

• _id -

  View id.

• _program -

  Program.

• _occlusionQuery -

  Occlusion query.

• _depth -

  Depth for sorting.

• _preserveState -

  Preserve internal draw state for next draw call submit.

void submit(ViewId _id, ProgramHandle _program, IndirectBufferHandle _indirectHandle, uint16_t _start = 0, uint16_t _num = 1, int32_t _depth = 0, bool _preserveState = false)

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

Attention

C99 equivalent is bgfx_submit_indirect.

Parameters

• _id -

  View id.

• _program -

  Program.

• _indirectHandle -

  Indirect buffer.

• _start -

  First element in indirect buffer.

• _num -

  Number of dispatches.

• _depth -

  Depth for sorting.

• _preserveState -

  Preserve internal draw state for next draw call submit.

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

Set compute index buffer.

Attention

C99 equivalent is bgfx_set_compute_index_buffer.

Parameters

• _stage -

  Compute stage.

• _handle -

  Index buffer handle.

• _access -

  Buffer access. See Access::Enum.

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

Set compute vertex buffer.

Attention

C99 equivalent is bgfx_set_compute_vertex_buffer.

Parameters

• _stage -

  Compute stage.

• _handle -

  Vertex buffer handle.

• _access -

  Buffer access. See Access::Enum.

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

Set compute dynamic index buffer.

Attention

C99 equivalent is bgfx_set_compute_dynamic_index_buffer.

Parameters

• _stage -

  Compute stage.

• _handle -

  Dynamic index buffer handle.

• _access -

  Buffer access. See Access::Enum.

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

Set compute dynamic vertex buffer.

Attention

C99 equivalent is bgfx_set_compute_dynamic_vertex_buffer.

Parameters

• _stage -

  Compute stage.

• _handle -

  Dynamic vertex buffer handle.

• _access -

  Buffer access. See Access::Enum.

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

Set compute indirect buffer.

Attention

C99 equivalent is bgfx_set_compute_indirect_buffer.

Parameters

• _stage -

  Compute stage.

• _handle -

  Indirect buffer handle.

• _access -

  Buffer access. See Access::Enum.

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

Set compute image from texture.

Attention

C99 equivalent is bgfx_set_image.

Parameters

• _stage -

  Texture unit.

• _sampler -

  Program sampler.

• _handle -

  Texture handle.

• _mip -

  Mip level.

• _access -

  Texture access. See Access::Enum.

• _format -

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

Dispatch compute.

Attention

C99 equivalent is bgfx_dispatch.

Parameters

• _id -

  View id.

• _handle -

  Compute program.

• _numX -

  Number of groups X.

• _numY -

  Number of groups Y.

• _numZ -

  Number of groups Z.

• _flags -

  View flags. Use

  • BGFX_VIEW_NONE - View will be rendered only once if stereo mode is enabled.
  • BGFX_VIEW_STEREO - View will be rendered for both eyes if stereo mode is enabled. When stereo mode is disabled this flag doesn’t have effect.

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

Dispatch compute indirect.

Attention

C99 equivalent is bgfx_dispatch_indirect.

Parameters

• _id -

  View id.

• _handle -

  Compute program.

• _indirectHandle -

  Indirect buffer.

• _start -

  First element in indirect buffer.

• _num -

  Number of dispatches.

• _flags -

  View flags. Use

  • BGFX_VIEW_NONE - View will be rendered only once if stereo mode is enabled.
  • BGFX_VIEW_STEREO - View will be rendered for both eyes if stereo mode is enabled. When stereo mode is disabled this flag doesn’t have effect.

void discard()

Discard all previously set state for draw or compute call.

Attention

C99 equivalent is bgfx_discard.

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

Blit texture 2D region between two 2D textures.

Attention

Destination texture must be create with BGFX_TEXTURE_BLIT_DST flag.

Attention

Availability depends on: BGFX_CAPS_TEXTURE_BLIT.

Attention

C99 equivalent is bgfx_blit.

Parameters

• _id -

  View id.

• _dst -

  Destination texture handle.

• _dstX -

  Destination texture X position.

• _dstY -

  Destination texture Y position.

• _src -

  Source texture handle.

• _srcX -

  Source texture X position.

• _srcY -

  Source texture Y position.

• _width -

  Width of region.

• _height -

  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 create with BGFX_TEXTURE_BLIT_DST flag.

Attention

Availability depends on: BGFX_CAPS_TEXTURE_BLIT.

Attention

C99 equivalent is bgfx_blit.

Parameters

• _id -

  View id.

• _dst -

  Destination texture handle.

• _dstMip -

  Destination texture mip level.

• _dstX -

  Destination texture X position.

• _dstY -

  Destination texture Y position.

• _dstZ -

  If texture is 2D this argument should be 0. If destination texture is cube this argument represent destination texture cube face. For 3D texture this argument represent destination texture Z position.

• _src -

  Source texture handle.

• _srcMip -

  Source texture mip level.

• _srcX -

  Source texture X position.

• _srcY -

  Source texture Y position.

• _srcZ -

  If texture is 2D this argument should be 0. If source texture is cube this argument represent source texture cube face. For 3D texture this argument represent source texture Z position.

• _width -

  Width of region.

• _height -

  Height of region.

• _depth -

  If texture is 3D this argument represent depth of region, otherwise is unused.

Draw

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

Debug

void bgfx::setMarker(const char *_marker)

Sets debug marker.

Attention

C99 equivalent is bgfx_set_marker.

void bgfx::setName(ShaderHandle _handle, const char *_name)

Set shader debug name.

Attention

C99 equivalent is bgfx_set_shader_name.

Parameters

• _handle -

  Shader handle.

• _name -

  Shader name.

void bgfx::setName(TextureHandle _handle, const char *_name)

Set texture debug name.

Attention

C99 equivalent is bgfx_set_texture_name.

Parameters

• _handle -

  Texture handle.

• _name -

  Texture name.

State

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

Set render states for draw primitive.

Remark

1. To setup more complex states use: BGFX_STATE_ALPHA_REF(_ref), BGFX_STATE_POINT_SIZE(_size), BGFX_STATE_BLEND_FUNC(_src, _dst), BGFX_STATE_BLEND_FUNC_SEPARATE(_srcRGB, _dstRGB, _srcA, _dstA) BGFX_STATE_BLEND_EQUATION(_equation) BGFX_STATE_BLEND_EQUATION_SEPARATE(_equationRGB, _equationA)
2. BGFX_STATE_BLEND_EQUATION_ADD is set when no other blend equation is specified.

Attention

C99 equivalent is bgfx_set_state.

Parameters

• _state -

  State flags. Default state for primitive type is triangles. See: BGFX_STATE_DEFAULT.

  • BGFX_STATE_ALPHA_WRITE - Enable alpha write.
  • BGFX_STATE_DEPTH_WRITE - Enable depth write.
  • 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_RGB_WRITE - Enable RGB write.
  • BGFX_STATE_MSAA - Enable MSAA.
  • BGFX_STATE_PT_[TRISTRIP/LINES/POINTS] - Primitive type.

• _rgba -

  Sets blend factor used by BGFX_STATE_BLEND_FACTOR and BGFX_STATE_BLEND_INV_FACTOR blend modes.

State Flags

BGFX_STATE_RGB_WRITE

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

Enable RGB write.

BGFX_STATE_ALPHA_WRITE

Enable alpha write.

BGFX_STATE_DEPTH_WRITE

Enable depth write.

BGFX_STATE_DEFAULT

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

Stencil

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

Set stencil test state.

Attention

C99 equivalent is bgfx_set_stencil.

Parameters

• _fstencil -

  Front stencil state.

• _bstencil -

  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

When scissor rectangle is changing per draw call inside the same view use bgfx::setScissor, otherwise prefer 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.

Return

Scissor cache index.

Attention

C99 equivalent is bgfx_set_scissor.

Parameters

• _x -

  Position x from the left corner of the window.

• _y -

  Position y from the top corner of the window.

• _width -

  Width of scissor region.

• _height -

  Height of scissor region.

void bgfx::setScissor(uint16_t _cache = UINT16_MAX)

Set scissor from cache for draw primitive.

Attention

C99 equivalent is bgfx_set_scissor_cached.

Parameters

• _cache -

  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.

Return

index into matrix cache.

Attention

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

Attention

C99 equivalent is bgfx_alloc_transform.

Parameters

• _transform -

  Pointer to Transform structure.

• _num -

  Number of matrices.

uint32_t bgfx::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.

Return

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

Attention

C99 equivalent is bgfx_set_transform.

Parameters

• _mtx -

  Pointer to first matrix in array.

• _num -

  Number of matrices in array.

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

Set model matrix from matrix cache for draw primitive.

Attention

C99 equivalent is bgfx_set_transform_cached.

Parameters

• _cache -

  Index in matrix cache.

• _num -

  Number of matrices from cache.

Conditional Rendering

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

Set condition for rendering.

Attention

C99 equivalent is bgfx_set_condition.

Parameters

• _handle -

  Occlusion query handle.

• _visible -

  Render if occlusion query is visible.

void bgfx::setIndexBuffer(IndexBufferHandle _handle)

Set index buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_index_buffer.

Parameters

• _handle -

  Index buffer.

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

Set index buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_index_buffer.

Parameters

• _handle -

  Index buffer.

• _firstIndex -

  First index to render.

• _numIndices -

  Number of indices to render.

void bgfx::setIndexBuffer(DynamicIndexBufferHandle _handle)

Set index buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_dynamic_index_buffer.

Parameters

• _handle -

  Dynamic index buffer.

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

Set index buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_dynamic_index_buffer.

Parameters

• _handle -

  Dynamic index buffer.

• _firstIndex -

  First index to render.

• _numIndices -

  Number of indices to render.

void bgfx::setIndexBuffer(const TransientIndexBuffer *_tib)

Set index buffer for draw primitive.

Remark

_tib pointer after this call is invalid.

Attention

C99 equivalent is bgfx_set_transient_index_buffer.

Parameters

• _tib -

  Transient index buffer.

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

Set index buffer for draw primitive.

Remark

_tib pointer after this call is invalid.

Attention

C99 equivalent is bgfx_set_transient_index_buffer.

Parameters

• _tib -

  Transient index buffer.

• _firstIndex -

  First index to render.

• _numIndices -

  Number of indices to render.

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

Set vertex buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_vertex_buffer.

Parameters

• _stream -

  Vertex stream.

• _handle -

  Vertex buffer.

void bgfx::setVertexBuffer(uint8_t _stream, VertexBufferHandle _handle, uint32_t _startVertex, uint32_t _numVertices)

Set vertex buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_vertex_buffer.

Parameters

• _stream -

  Vertex stream.

• _handle -

  Vertex buffer.

• _startVertex -

  First vertex to render.

• _numVertices -

  Number of vertices to render.

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

Set vertex buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_dynamic_vertex_buffer.

Parameters

• _stream -

  Vertex stream.

• _handle -

  Dynamic vertex buffer.

void bgfx::setVertexBuffer(uint8_t _stream, DynamicVertexBufferHandle _handle, uint32_t _startVertex, uint32_t _numVertices)

Set vertex buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_dynamic_vertex_buffer.

Parameters

• _stream -

  Vertex stream.

• _handle -

  Dynamic vertex buffer.

• _startVertex -

  First vertex to render.

• _numVertices -

  Number of vertices to render.

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

Set vertex buffer for draw primitive.

Remark

_tvb pointer after this call is invalid.

Attention

C99 equivalent is bgfx_set_transient_vertex_buffer.

Parameters

• _stream -

  Vertex stream.

• _tvb -

  Transient vertex buffer.

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

Set vertex buffer for draw primitive.

Remark

_tvb pointer after this call is invalid.

Attention

C99 equivalent is bgfx_set_transient_vertex_buffer.

Parameters

• _stream -

  Vertex stream.

• _tvb -

  Transient vertex buffer.

• _startVertex -

  First vertex to render.

• _numVertices -

  Number of vertices to render.

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

Set instance data buffer for draw primitive.

Remark

_idb pointer after this call is invalid.

Attention

C99 equivalent is bgfx_set_instance_data_buffer.

Parameters

• _idb -

  Transient instance data buffer.

• _num -

  Number of data instances.

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

Set instance data buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_instance_data_from_vertex_buffer.

Parameters

• _handle -

  Vertex buffer.

• _start -

  First instance data.

• _num -

  Number of data instances.

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

Set instance data buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_instance_data_from_dynamic_vertex_buffer.

Parameters

• _handle -

  Vertex buffer.

• _start -

  First instance data.

• _num -

  Number of data instances.

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

Set texture stage for draw primitive.

Attention

C99 equivalent is bgfx_set_texture.

Parameters

• _stage -

  Texture unit.

• _sampler -

  Program sampler.

• _handle -

  Texture handle.

• _flags -

  Texture sampling mode. Default value UINT32_MAX uses texture sampling settings from the texture.

  • BGFX_TEXTURE_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.
  • BGFX_TEXTURE_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

Within view all draw commands are executed after blit and compute commands.

void bgfx::submit(ViewId _id, ProgramHandle _program, int32_t _depth = 0, bool _preserveState = false)

Submit primitive for rendering.

Attention

C99 equivalent is bgfx_submit.

Parameters

• _id -

  View id.

• _program -

  Program.

• _depth -

  Depth for sorting.

• _preserveState -

  Preserve internal draw state for next draw call submit.

void bgfx::submit(ViewId _id, ProgramHandle _program, OcclusionQueryHandle _occlusionQuery, int32_t _depth = 0, bool _preserveState = false)

Submit primitive with occlusion query for rendering.

Attention

C99 equivalent is bgfx_submit_occlusion_query.

Parameters

• _id -

  View id.

• _program -

  Program.

• _occlusionQuery -

  Occlusion query.

• _depth -

  Depth for sorting.

• _preserveState -

  Preserve internal draw state for next draw call submit.

void bgfx::submit(ViewId _id, ProgramHandle _program, IndirectBufferHandle _indirectHandle, uint16_t _start = 0, uint16_t _num = 1, int32_t _depth = 0, bool _preserveState = false)

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

Attention

C99 equivalent is bgfx_submit_indirect.

Parameters

• _id -

  View id.

• _program -

  Program.

• _indirectHandle -

  Indirect buffer.

• _start -

  First element in indirect buffer.

• _num -

  Number of dispatches.

• _depth -

  Depth for sorting.

• _preserveState -

  Preserve internal draw state for next draw call submit.

Compute

Compute state is not preserved between two compute dispatches. All state is cleared after calling bgfx::dispatch.

struct bgfx::Access

Access mode enum.

Attention

C99 equivalent is bgfx_access_t.

Public Types

enum Enum

Access:

Values:

Read

Read.

Write

Write.

ReadWrite

Read and write.

Count

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

Set compute index buffer.

Attention

C99 equivalent is bgfx_set_compute_index_buffer.

Parameters

• _stage -

  Compute stage.

• _handle -

  Index buffer handle.

• _access -

  Buffer access. See Access::Enum.

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

Set compute vertex buffer.

Attention

C99 equivalent is bgfx_set_compute_vertex_buffer.

Parameters

• _stage -

  Compute stage.

• _handle -

  Vertex buffer handle.

• _access -

  Buffer access. See Access::Enum.

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

Set compute dynamic index buffer.

Attention

C99 equivalent is bgfx_set_compute_dynamic_index_buffer.

Parameters

• _stage -

  Compute stage.

• _handle -

  Dynamic index buffer handle.

• _access -

  Buffer access. See Access::Enum.

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

Set compute dynamic vertex buffer.

Attention

C99 equivalent is bgfx_set_compute_dynamic_vertex_buffer.

Parameters

• _stage -

  Compute stage.

• _handle -

  Dynamic vertex buffer handle.

• _access -

  Buffer access. See Access::Enum.

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

Set compute indirect buffer.

Attention

C99 equivalent is bgfx_set_compute_indirect_buffer.

Parameters

• _stage -

  Compute stage.

• _handle -

  Indirect buffer handle.

• _access -

  Buffer access. See Access::Enum.

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

Set compute image from texture.

Attention

C99 equivalent is bgfx_set_image.

Parameters

• _stage -

  Texture unit.

• _sampler -

  Program sampler.

• _handle -

  Texture handle.

• _mip -

  Mip level.

• _access -

  Texture access. See Access::Enum.

• _format -

  Texture format. See: TextureFormat::Enum.

Within view all compute commands are dispatched after blit commands, and before draw commands.

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

Dispatch compute.

Attention

C99 equivalent is bgfx_dispatch.

Parameters

• _id -

  View id.

• _handle -

  Compute program.

• _numX -

  Number of groups X.

• _numY -

  Number of groups Y.

• _numZ -

  Number of groups Z.

• _flags -

  View flags. Use

  • BGFX_VIEW_NONE - View will be rendered only once if stereo mode is enabled.
  • BGFX_VIEW_STEREO - View will be rendered for both eyes if stereo mode is enabled. When stereo mode is disabled this flag doesn’t have effect.

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

Dispatch compute indirect.

Attention

C99 equivalent is bgfx_dispatch_indirect.

Parameters

• _id -

  View id.

• _handle -

  Compute program.

• _indirectHandle -

  Indirect buffer.

• _start -

  First element in indirect buffer.

• _num -

  Number of dispatches.

• _flags -

  View flags. Use

  • BGFX_VIEW_NONE - View will be rendered only once if stereo mode is enabled.
  • BGFX_VIEW_STEREO - View will be rendered for both eyes if stereo mode is enabled. When stereo mode is disabled this flag doesn’t have effect.

Blit

Within view all blit commands are executed before compute, and draw 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 texture 2D region between two 2D textures.

Attention

Destination texture must be create with BGFX_TEXTURE_BLIT_DST flag.

Attention

Availability depends on: BGFX_CAPS_TEXTURE_BLIT.

Attention

C99 equivalent is bgfx_blit.

Parameters

• _id -

  View id.

• _dst -

  Destination texture handle.

• _dstX -

  Destination texture X position.

• _dstY -

  Destination texture Y position.

• _src -

  Source texture handle.

• _srcX -

  Source texture X position.

• _srcY -

  Source texture Y position.

• _width -

  Width of region.

• _height -

  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 create with BGFX_TEXTURE_BLIT_DST flag.

Attention

Availability depends on: BGFX_CAPS_TEXTURE_BLIT.

Attention

C99 equivalent is bgfx_blit.

Parameters

• _id -

  View id.

• _dst -

  Destination texture handle.

• _dstMip -

  Destination texture mip level.

• _dstX -

  Destination texture X position.

• _dstY -

  Destination texture Y position.

• _dstZ -

  If texture is 2D this argument should be 0. If destination texture is cube this argument represent destination texture cube face. For 3D texture this argument represent destination texture Z position.

• _src -

  Source texture handle.

• _srcMip -

  Source texture mip level.

• _srcX -

  Source texture X position.

• _srcY -

  Source texture Y position.

• _srcZ -

  If texture is 2D this argument should be 0. If source texture is cube this argument represent source texture cube face. For 3D texture this argument represent source texture Z position.

• _width -

  Width of region.

• _height -

  Height of region.

• _depth -

  If texture is 3D this argument represent depth of region, otherwise is unused.

Resources

struct bgfx::Memory

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

Attention

C99 equivalent 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 equivalent is bgfx_alloc.

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 equivalent is bgfx_copy.

Parameters

• _data -

  Pointer to data to be copied.

• _size -

  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 pointer to data. You can pass ReleaseFn function pointer to release this memory after it’s consumed, or 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 equivalent are bgfx_make_ref, bgfx_make_ref_release.

Shaders and Programs

ShaderHandle bgfx::createShader(const Memory *_mem)

Create shader from memory buffer.

Attention

C99 equivalent is bgfx_create_shader.

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

Returns num of uniforms, and uniform handles used inside shader.

Return

Number of uniforms used by shader.

Remark

Only non-predefined uniforms are returned.

Attention

C99 equivalent is bgfx_get_shader_uniforms.

Parameters

• _handle -

  Shader handle.

• _uniforms -

  UniformHandle array where data will be stored.

• _max -

  Maximum capacity of array.

void bgfx::destroy(ShaderHandle _handle)

Destroy shader. Once program is created with shader it is safe to destroy shader.

Attention

C99 equivalent is bgfx_destroy_shader.

Parameters

• _handle -

  Shader handle.

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

Create program with vertex and fragment shaders.

Return

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

Attention

C99 equivalent is bgfx_create_program.

Parameters

• _vsh -

  Vertex shader.

• _fsh -

  Fragment shader.

• _destroyShaders -

  If true, shaders will be destroyed when program is destroyed.

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

Create program with compute shader.

Return

Program handle.

Attention

C99 equivalent is bgfx_create_compute_program.

Parameters

• _csh -

  Compute shader.

• _destroyShader -

  If true, shader will be destroyed when program is destroyed.

void bgfx::destroy(ProgramHandle _handle)

Destroy program.

Attention

C99 equivalent is bgfx_destroy_program.

Parameters

• _handle -

  Program handle.

Uniforms

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

Create shader uniform parameter.

Return

Handle to uniform object.

Remark

1. Uniform names are unique. It’s valid to call bgfx::createUniform multiple times with the same uniform name. The library will always return the same handle, but the handle reference count will be incremented. This means that the same number of bgfx::destroyUniform must be called to properly destroy the uniform.
2. Predefined uniforms (declared in bgfx_shader.sh):
   • u_viewRect vec4(x, y, width, height) - view rectangle for current view.
   • 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 equivalent is bgfx_create_uniform.

Parameters

• _name -

  Uniform name in shader.

• _type -

  Type of uniform (See: bgfx::UniformType).

• _num -

  Number of elements in array.

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

Retrieve uniform info.

Attention

C99 equivalent is bgfx_get_uniform_info.

Parameters

• _handle -

  Handle to uniform object.

• _info -

  Uniform info.

void bgfx::destroy(UniformHandle _handle)

Destroy shader uniform parameter.

Attention

C99 equivalent is bgfx_destroy_uniform.

Parameters

• _handle -

  Handle to uniform object.

struct bgfx::UniformType

Uniform type enum.

Attention

C99 equivalent is bgfx_uniform_type_t.

Public Types

enum Enum

Uniform types:

Values:

Int1

Int, used for samplers only.

End

Reserved, do not use.

Vec4

4 floats vector.

Mat3

3x3 matrix.

Mat4

4x4 matrix.

Count

struct bgfx::UniformInfo

Uniform info.

Attention

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

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

Create static vertex buffer.

Return

Static vertex buffer handle.

Attention

C99 equivalent is bgfx_create_vertex_buffer.

Parameters

• _mem -

  Vertex buffer data.

• _decl -

  Vertex declaration.

• _flags -

  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 different amount of data is passed. If this flag is not specified if more data is passed on update buffer will be trimmed to fit 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::destroy(VertexBufferHandle _handle)

Destroy static vertex buffer.

Attention

C99 equivalent is bgfx_destroy_vertex_buffer.

Parameters

• _handle -

  Static vertex buffer handle.

struct bgfx::VertexDecl

Vertex declaration.

Attention

C99 equivalent is bgfx_vertex_decl_t.

Public Functions

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

Start VertexDecl.

Attention

C99 equivalent is bgfx_vertex_decl_begin.

void end()

End VertexDecl.

Attention

C99 equivalent is bgfx_vertex_decl_end.

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

Add attribute to VertexDecl.

Remark

Must be called between begin/end.

Attention

C99 equivalent is bgfx_vertex_decl_add.

Parameters

• _attrib -

  Attribute semantics. See: bgfx::Attrib

• _num -

  Number of elements 1, 2, 3 or 4.

• _type -

  Element type.

• _normalized -

  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 -

  Packaging rule for vertexPack, vertexUnpack, and vertexConvert for AttribType::Uint8 and AttribType::Int16. Unpacking code must be implemented inside vertex shader.

VertexDecl &skip(uint8_t _num)

Skip _num bytes in vertex stream.

Attention

C99 equivalent is bgfx_vertex_decl_skip.

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

Decode attribute.

Attention

C99 equivalent is ``.

bool has(Attrib::Enum _attrib) const

Returns true if VertexDecl contains attribute.

uint16_t getOffset(Attrib::Enum _attrib) const

Returns relative attribute offset from the vertex.

uint16_t getStride() const

Returns vertex stride.

uint32_t getSize(uint32_t _num) const

Returns size of vertex buffer for number of vertices.

struct bgfx::Attrib

Vertex attribute enum.

Attention

C99 equivalent is bgfx_attrib_t.

Public Types

enum Enum

Corresponds to vertex shader attribute. Attributes:

Values:

Position

a_position

Normal

a_normal

Tangent

a_tangent

Bitangent

a_bitangent

Color0

a_color0

Color1

a_color1

Color2

a_color2

Color3

a_color3

Indices

a_indices

Weight

a_weight

TexCoord0

a_texcoord0

TexCoord1

a_texcoord1

TexCoord2

a_texcoord2

TexCoord3

a_texcoord3

TexCoord4

a_texcoord4

TexCoord5

a_texcoord5

TexCoord6

a_texcoord6

TexCoord7

a_texcoord7

Count

DynamicVertexBufferHandle bgfx::createDynamicVertexBuffer(uint32_t _num, const VertexDecl &_decl, uint16_t _flags = BGFX_BUFFER_NONE)

Create empty dynamic vertex buffer.

Return

Dynamic vertex buffer handle.

Attention

C99 equivalent is bgfx_create_dynamic_vertex_buffer.

Parameters

• _num -

  Number of vertices.

• _decl -

  Vertex declaration.

• _flags -

  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 different amount of data is passed. If this flag is not specified if more data is passed on update buffer will be trimmed to fit 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.

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

Create dynamic vertex buffer and initialize it.

Return

Dynamic vertex buffer handle.

Attention

C99 equivalent is bgfx_create_dynamic_vertex_buffer_mem.

Parameters

• _mem -

  Vertex buffer data.

• _decl -

  Vertex declaration.

• _flags -

  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 different amount of data is passed. If this flag is not specified if more data is passed on update buffer will be trimmed to fit 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::updateDynamicVertexBuffer(DynamicVertexBufferHandle _handle, uint32_t _startVertex, const Memory *_mem)

Update dynamic vertex buffer.

Attention

C99 equivalent is bgfx_update_dynamic_vertex_buffer.

Parameters

• _handle -

  Dynamic vertex buffer handle.

• _startVertex -

  Start vertex.

• _mem -

  Vertex buffer data.

void bgfx::destroy(DynamicVertexBufferHandle _handle)

Destroy dynamic vertex buffer.

Attention

C99 equivalent is bgfx_destroy_dynamic_vertex_buffer.

Parameters

• _handle -

  Dynamic vertex buffer handle.

uint32_t bgfx::getAvailTransientVertexBuffer(uint32_t _num, const VertexDecl &_decl)

Returns number of available vertices.

Attention

C99 equivalent is bgfx_get_avail_transient_vertex_buffer.

Parameters

• _num -

  Number of required vertices.

• _decl -

  Vertex declaration.

void bgfx::allocTransientVertexBuffer(TransientVertexBuffer *_tvb, uint32_t _num, const VertexDecl &_decl)

Allocate transient vertex buffer.

Attention

C99 equivalent is bgfx_alloc_transient_vertex_buffer.

Parameters

• _tvb -

  TransientVertexBuffer structure is filled and is valid for the duration of frame, and it can be reused for multiple draw calls.

• _num -

  Number of vertices to allocate.

• _decl -

  Vertex declaration.

Index Buffers

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

Create static index buffer.

Attention

C99 equivalent is bgfx_create_index_buffer.

Parameters

• _mem -

  Index buffer data.

• _flags -

  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 different amount of data is passed. If this flag is not specified if more data is passed on update buffer will be trimmed to fit 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::destroy(IndexBufferHandle _handle)

Destroy static index buffer.

Attention

C99 equivalent is bgfx_destroy_index_buffer.

Parameters

• _handle -

  Static index buffer handle.

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

Create empty dynamic index buffer.

Return

Dynamic index buffer handle.

Attention

C99 equivalent is bgfx_create_dynamic_index_buffer.

Parameters

• _num -

  Number of indices.

• _flags -

  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 different amount of data is passed. If this flag is not specified if more data is passed on update buffer will be trimmed to fit 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.

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

Create dynamic index buffer and initialized it.

Return

Dynamic index buffer handle.

Attention

C99 equivalent is bgfx_create_dynamic_index_buffer_mem.

Parameters

• _mem -

  Index buffer data.

• _flags -

  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 different amount of data is passed. If this flag is not specified if more data is passed on update buffer will be trimmed to fit 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::updateDynamicIndexBuffer(DynamicIndexBufferHandle _handle, uint32_t _startIndex, const Memory *_mem)

Update dynamic index buffer.

Attention

C99 equivalent is bgfx_update_dynamic_index_buffer.

Parameters

• _handle -

  Dynamic index buffer handle.

• _startIndex -

  Start index.

• _mem -

  Index buffer data.

void bgfx::destroy(DynamicIndexBufferHandle _handle)

Destroy dynamic index buffer.

Attention

C99 equivalent is bgfx_destroy_dynamic_index_buffer.

Parameters

• _handle -

  Dynamic index buffer handle.

uint32_t bgfx::getAvailTransientIndexBuffer(uint32_t _num)

Returns number of available indices.

Attention

C99 equivalent is bgfx_get_avail_transient_index_buffer.

Parameters

• _num -

  Number of required indices.

void bgfx::allocTransientIndexBuffer(TransientIndexBuffer *_tib, uint32_t _num)

Allocate transient index buffer.

Remark

Only 16-bit index buffer is supported.

Attention

C99 equivalent is bgfx_alloc_transient_index_buffer.

Parameters

• _tib -

  TransientIndexBuffer structure is filled and is valid for the duration of frame, and it can be reused for multiple draw calls.

• _num -

  Number of indices to allocate.

Textures

struct bgfx::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 equivalent is bgfx_texture_format_t.

Public Types

enum Enum

Texture formats:

Values:

BC1

DXT1.

BC2

DXT3.

BC3

DXT5.

BC4

LATC1/ATI1.

BC5

LATC2/ATI2.

BC6H

BC6H.

BC7

BC7.

ETC1

ETC1 RGB8.

ETC2

ETC2 RGB8.

ETC2A

ETC2 RGBA8.

ETC2A1

ETC2 RGB8A1.

PTC12

PVRTC1 RGB 2BPP.

PTC14

PVRTC1 RGB 4BPP.

PTC12A

PVRTC1 RGBA 2BPP.

PTC14A

PVRTC1 RGBA 4BPP.

PTC22

PVRTC2 RGBA 2BPP.

PTC24

PVRTC2 RGBA 4BPP.

Unknown

R1

A8

R8

R8I

R8U

R8S

R16

R16I

R16U

R16F

R16S

R32I

R32U

R32F

RG8

RG8I

RG8U

RG8S

RG16

RG16I

RG16U

RG16F

RG16S

RG32I

RG32U

RG32F

RGB8

RGB8I

RGB8U

RGB8S

RGB9E5F

BGRA8

RGBA8

RGBA8I

RGBA8U

RGBA8S

RGBA16

RGBA16I

RGBA16U

RGBA16F

RGBA16S

RGBA32I

RGBA32U

RGBA32F

R5G6B5

RGBA4

RGB5A1

RGB10A2

RG11B10F

UnknownDepth

D16

D24

D24S8

D32

D16F

D24F

D32F

D0S8

Count

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

Validate texture parameters.

Return

True if texture can be successfully created.

Attention

C99 equivalent is bgfx_is_texture_valid.

Parameters

• _depth -

  Depth dimension of volume texture.

• _cubeMap -

  Indicates that texture contains cubemap.

• _numLayers -

  Number of layers in texture array.

• _format -

  Texture format. See: TextureFormat::Enum.

• _flags -

  Texture flags. See BGFX_TEXTURE_*.

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 equivalent is bgfx_calc_texture_size.

Parameters

• _info -

  Resulting texture info structure.

• _width -

  Width.

• _height -

  Height.

• _depth -

  Depth dimension of volume texture.

• _cubeMap -

  Indicates that texture contains cubemap.

• _hasMips -

  Indicates that texture contains full mip-map chain.

• _numLayers -

  Number of layers in texture array.

• _format -

  Texture format. See: TextureFormat::Enum.

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

Create texture from memory buffer.

Return

Texture handle.

Attention

C99 equivalent is bgfx_create_texture.

Parameters

• _mem -

  DDS, KTX or PVR texture data.

• _flags -

  Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_TEXTURE_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.
  • BGFX_TEXTURE_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

• _skip -

  Skip top level mips when parsing texture.

• _info -

  When non-NULL is specified it returns parsed texture information.

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

Create 2D texture.

Attention

C99 equivalent is bgfx_create_texture_2d.

Parameters

• _width -

  Width.

• _height -

  Height.

• _hasMips -

  Indicates that texture contains full mip-map chain.

• _numLayers -

  Number of layers in texture array. Must be 1 if caps BGFX_CAPS_TEXTURE_2D_ARRAY flag is not set.

• _format -

  Texture format. See: TextureFormat::Enum.

• _flags -

  Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_TEXTURE_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.
  • BGFX_TEXTURE_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

• _mem -

  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, uint32_t _flags = BGFX_TEXTURE_NONE)

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

Attention

C99 equivalent is bgfx_create_texture_2d_scaled.

Parameters

• _ratio -

  Frame buffer size in respect to back-buffer size. See: BackbufferRatio::Enum.

• _hasMips -

  Indicates that texture contains full mip-map chain.

• _numLayers -

  Number of layers in texture array. Must be 1 if caps BGFX_CAPS_TEXTURE_2D_ARRAY flag is not set.

• _format -

  Texture format. See: TextureFormat::Enum.

• _flags -

  Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_TEXTURE_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.
  • BGFX_TEXTURE_[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

C99 equivalent is bgfx_update_texture_2d.

Parameters

• _handle -

  Texture handle.

• _layer -

  Layers in texture array.

• _mip -

  Mip level.

• _x -

  X offset in texture.

• _y -

  Y offset in texture.

• _width -

  Width of texture block.

• _height -

  Height of texture block.

• _mem -

  Texture update data.

• _pitch -

  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, uint32_t _flags = BGFX_TEXTURE_NONE, const Memory *_mem = NULL)

Create 3D texture.

Attention

C99 equivalent is bgfx_create_texture_3d.

Parameters

• _width -

  Width.

• _height -

  Height.

• _depth -

  Depth.

• _hasMips -

  Indicates that texture contains full mip-map chain.

• _format -

  Texture format. See: TextureFormat::Enum.

• _flags -

  Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_TEXTURE_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.
  • BGFX_TEXTURE_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

• _mem -

  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

C99 equivalent is bgfx_update_texture_3d.

Parameters

• _handle -

  Texture handle.

• _mip -

  Mip level.

• _x -

  X offset in texture.

• _y -

  Y offset in texture.

• _z -

  Z offset in texture.

• _width -

  Width of texture block.

• _height -

  Height of texture block.

• _depth -

  Depth of texture block.

• _mem -

  Texture update data.

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

Create Cube texture.

Attention

C99 equivalent is bgfx_create_texture_cube.

Parameters

• _size -

  Cube side size.

• _hasMips -

  Indicates that texture contains full mip-map chain.

• _numLayers -

  Number of layers in texture array. Must be 1 if caps BGFX_CAPS_TEXTURE_CUBE_ARRAY flag is not set.

• _format -

  Texture format. See: TextureFormat::Enum.

• _flags -

  Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_TEXTURE_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.
  • BGFX_TEXTURE_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

• _mem -

  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

C99 equivalent is bgfx_update_texture_cube.

Parameters

• _handle -

  Texture handle.

• _layer -

  Layers in texture array.

• _side -

  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    |
             | |        |
             | +---->+x |
  +----------+----------+----------+----------+
  |+y       1|+y       4|+y       0|+y       5|
  | ^  -x    | ^  +z    | ^  +x    | ^  -z    |
  | |        | |        | |        | |        |
  | +---->+z | +---->+x | +---->-z | +---->-x |
  +----------+----------+----------+----------+
             |+z       3|
             | ^  -y    |
             | |        |
             | +---->+x |
             +----------+
  

• _mip -

  Mip level.

• _x -

  X offset in texture.

• _y -

  Y offset in texture.

• _width -

  Width of texture block.

• _height -

  Height of texture block.

• _mem -

  Texture update data.

• _pitch -

  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.

Return

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

Attention

Texture must be created with BGFX_TEXTURE_READ_BACK flag.

Attention

Availability depends on: BGFX_CAPS_TEXTURE_READ_BACK.

Attention

C99 equivalent is bgfx_read_texture.

Parameters

• _handle -

  Texture handle.

• _data -

  Destination buffer.

• _mip -

  Mip level.

void *bgfx::getDirectAccessPtr(TextureHandle _handle)

Returns texture direct access pointer.

Return

Pointer to texture memory. If pointer is NULL direct access is not supported. If pointer is UINTPTR_MAX sentinel value it means texture is pending creation.

Attention

Availability depends on: BGFX_CAPS_TEXTURE_DIRECT_ACCESS.

Attention

C99 equivalent is bgfx_get_direct_access_ptr.

Parameters

• _handle -

  Texture handle.

void bgfx::destroy(TextureHandle _handle)

Destroy texture.

Attention

C99 equivalent is bgfx_destroy_texture.

Parameters

• _handle -

  Texture handle.

Frame Buffers

FrameBufferHandle bgfx::createFrameBuffer(uint16_t _width, uint16_t _height, TextureFormat::Enum _format, uint32_t _textureFlags = BGFX_TEXTURE_U_CLAMP|BGFX_TEXTURE_V_CLAMP)

Create frame buffer (simple).

Return

Handle to frame buffer object.

Attention

C99 equivalent is bgfx_create_frame_buffer.

Parameters

• _width -

  Texture width.

• _height -

  Texture height.

• _format -

  Texture format. See: TextureFormat::Enum.

• _textureFlags -

  Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_TEXTURE_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.
  • BGFX_TEXTURE_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

FrameBufferHandle bgfx::createFrameBuffer(BackbufferRatio::Enum _ratio, TextureFormat::Enum _format, uint32_t _textureFlags = BGFX_TEXTURE_U_CLAMP|BGFX_TEXTURE_V_CLAMP)

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

Return

Handle to frame buffer object.

Attention

C99 equivalent is bgfx_create_frame_buffer_scaled.

Parameters

• _ratio -

  Frame buffer size in respect to back-buffer size. See: BackbufferRatio::Enum.

• _format -

  Texture format. See: TextureFormat::Enum.

• _textureFlags -

  Default texture sampling mode is linear, and wrap mode is repeat.

  • BGFX_TEXTURE_[U/V/W]_[MIRROR/CLAMP] - Mirror or clamp to edge wrap mode.
  • BGFX_TEXTURE_[MIN/MAG/MIP]_[POINT/ANISOTROPIC] - Point or anisotropic sampling.

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

Create MRT frame buffer from texture handles (simple).

Return

Handle to frame buffer object.

Attention

C99 equivalent is bgfx_create_frame_buffer_from_handles.

Parameters

• _num -

  Number of texture attachments.

• _handles -

  Texture attachments.

• _destroyTextures -

  If true, textures will be destroyed when frame buffer is destroyed.

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

Create frame buffer for multiple window rendering.

Return

Handle to frame buffer object.

Remark

Frame buffer cannot be used for sampling.

Attention

C99 equivalent is bgfx_create_frame_buffer_from_nwh.

Parameters

• _nwh -

  OS’ target native window handle.

• _width -

  Window back buffer width.

• _height -

  Window back buffer height.

• _depthFormat -

  Window back buffer depth format.

struct bgfx::Attachment

Frame buffer texture attachemnt info.

Attention

C99 equivalent is bgfx_attachment_t.

Public Members

TextureHandle handle

Texture handle.

uint16_t mip

Mip level.

uint16_t layer

Cubemap side or depth layer/slice.

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.

Return

Handle to frame buffer object.

Attention

C99 equivalent is bgfx_create_frame_buffer_from_attachment.

Parameters

• _num -

  Number of texture attachments.

• _attachment -

  Attachment texture info. See: Attachment.

• _destroyTextures -

  If true, textures will be destroyed when frame buffer is destroyed.

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

Obtain texture handle of frame buffer attachment.

Return

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

Parameters

• _handle -

  Frame buffer handle.

• _attachment -

  Frame buffer attachment index.

void bgfx::destroy(FrameBufferHandle _handle)

Destroy frame buffer.

Attention

C99 equivalent is bgfx_destroy_frame_buffer.

Parameters

• _handle -

  Frame buffer handle.

Instance Buffer

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

Returns number of available instance buffer slots.

Attention

C99 equivalent is bgfx_get_avail_instance_data_buffer.

Parameters

• _num -

  Number of required instances.

• _stride -

  Stride per instance.

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

Allocate instance data buffer.

Attention

C99 equivalent is bgfx_alloc_instance_data_buffer.

Parameters

• _idb -

  InstanceDataBuffer structure is filled and is valid for duration of frame, and it can be reused for multiple draw calls.

• _num -

  Number of instances.

• _stride -

  Instance stride. Must be multiple of 16.

Indirect Buffer

IndirectBufferHandle bgfx::createIndirectBuffer(uint32_t _num)

Create draw indirect buffer.

Return

Indirect buffer handle.

Attention

C99 equivalent is bgfx_create_indirect_buffer.

Parameters

• _num -

  Number of indirect calls.

void bgfx::destroy(IndirectBufferHandle _handle)

Destroy draw indirect buffer.

Attention

C99 equivalent is bgfx_destroy_indirect_buffer.

Parameters

• _handle -

  Indirect buffer handle.

Occlusion Query

OcclusionQueryHandle bgfx::createOcclusionQuery()

Create occlusion query.

Return

Handle to occlusion query object.

Attention

C99 equivalent is bgfx_create_occlusion_query.

struct bgfx::OcclusionQueryResult

Occlusion query result.

Attention

C99 equivalent is bgfx_occlusion_query_result_t.

Public Types

enum Enum

Occlusion query results:

Values:

Invisible

Query failed test.

Visible

Query passed test.

NoResult

Query result is not available yet.

Count

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

Retrieve occlusion query result from previous frame.

Return

Occlusion query result.

Attention

C99 equivalent is bgfx_get_result.

Parameters

• _handle -

  Handle to occlusion query object.

• _result -

  Number of pixels that passed test. This argument can be NULL if result of occlusion query is not needed.

void bgfx::destroy(OcclusionQueryHandle _handle)

Destroy occlusion query.

Attention

C99 equivalent is bgfx_destroy_occlusion_query.

Parameters

• _handle -

  Handle to occlusion query object.