API Reference¶

Initialization and Shutdown¶

bool bgfx::init(RendererType::Enum _type, uint16_t _vendorId, uint16_t _deviceId, CallbackI *_callback, bx::ReallocatorI *_reallocator)¶

Initialize bgfx library.

Return

true if initialization is sucessful.

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.
  • BGFX_PCI_ID_AMD - AMD.
  • BGFX_PCI_ID_INTEL - Intel.
  • BGFX_PCI_ID_NVIDIA - nVidia.

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

• _reallocator -

  Custom allocator. When custom allocator is not specified, library uses default CRT allocator. The library assumes icustom 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 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¶

Debug¶

Querying information¶

Platform specific¶

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

RenderFrame::Enum bgfx::renderFrame()¶

Render frame.

Return

Current renderer state. See: bgfx::RenderFrame.

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.

struct bgfx::RenderFrame¶

Render frame enum.

Attention

C99 equivalent is bgfx_render_frame_t.

void bgfx::setPlatformData(const PlatformData &_hooks)¶

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.

Miscellaneous¶

void bgfx::discard()¶

Discard all previously set state for draw or compute call.

Attention

C99 equivalent is bgfx_discard.

uint32_t bgfx::touch(uint8_t _id)¶

Touch view.

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

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::saveScreenShot(const char *_filePath)¶

Request screen shot.

Remark

bgfx::CallbackI::screenShot must be implemented.

Attention

C99 equivalent is bgfx_save_screen_shot.

Parameters

• _filePath -

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

State¶

Buffers¶

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, 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, uint32_t _firstIndex, uint32_t _numIndices)¶

Set index buffer for draw primitive.

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::setIndexBuffer(const TransientIndexBuffer *_tib)¶

Set index buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_transient_index_buffer.

Parameters

• _tib -

  Transient index buffer.

void bgfx::setVertexBuffer(VertexBufferHandle _handle)¶

Set vertex buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_vertex_buffer.

Parameters

• _handle -

  Vertex buffer.

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

Set vertex buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_vertex_buffer.

Parameters

• _handle -

  Vertex buffer.

• _startVertex -

  First vertex to render.

• _numVertices -

  Number of vertices to render.

void bgfx::setVertexBuffer(DynamicVertexBufferHandle _handle, uint32_t _numVertices)¶

Set vertex buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_dynamic_vertex_buffer.

Parameters

• _handle -

  Dynamic vertex buffer.

• _numVertices -

  Number of vertices to render.

void bgfx::setVertexBuffer(const TransientVertexBuffer *_tvb)¶

Set vertex buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_transient_vertex_buffer.

Parameters

• _tvb -

  Transient vertex buffer.

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

Set vertex buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_transient_vertex_buffer.

Parameters

• _tvb -

  Transient vertex buffer.

• _startVertex -

  First vertex to render.

• _numVertices -

  Number of vertices to render.

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

Set instance data buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_instance_data_buffer.

void bgfx::setInstanceDataBuffer(VertexBufferHandle _handle, uint32_t _startVertex, uint32_t _num)¶

Set instance data buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_instance_data_from_vertex_buffer.

void bgfx::setInstanceDataBuffer(DynamicVertexBufferHandle _handle, uint32_t _startVertex, uint32_t _num)¶

Set instance data buffer for draw primitive.

Attention

C99 equivalent is bgfx_set_instance_data_from_dynamic_vertex_buffer.

Textures¶

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

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.

• _flags -

  Texture sampler filtering flags. UINT32_MAX use the sampler filtering mode set by texture.

void bgfx::setTexture(uint8_t _stage, UniformHandle _sampler, FrameBufferHandle _handle, uint8_t _attachment, uint32_t _flags)¶

Set texture stage for draw primitive.

Attention

C99 equivalent is bgfx_set_texture_from_frame_buffer.

Parameters

• _stage -

  Texture unit.

• _sampler -

  Program sampler.

• _handle -

  Frame buffer handle.

• _attachment -

  Frame buffer attachment index.

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

Submit¶

uint32_t bgfx::submit(uint8_t _id, ProgramHandle _handle, int32_t _depth)¶

Submit primitive for rendering.

Return

Number of draw calls.

Attention

C99 equivalent is bgfx_submit.

Parameters

• _id -

  View id.

• _handle -

  Program.

• _depth -

  Depth for sorting.

uint32_t bgfx::submit(uint8_t _id, ProgramHandle _handle, IndirectBufferHandle _indirectHandle, uint16_t _start, uint16_t _num, int32_t _depth)¶

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

Attention

C99 equivalent is bgfx_submit_indirect.

Parameters

• _id -

  View id.

• _handle -

  Program.

• _indirectHandle -

  Indirect buffer.

• _start -

  First element in indirect buffer.

• _num -

  Number of dispatches.

• _depth -

  Depth for sorting.

Buffers¶

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.

Images¶

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

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 bgfx::setImage(uint8_t _stage, UniformHandle _sampler, FrameBufferHandle _handle, uint8_t _attachment, Access::Enum _access, TextureFormat::Enum _format)¶

Set compute image from frame buffer texture.

Attention

C99 equivalent is bgfx_set_image_from_frame_buffer.

Parameters

• _stage -

  Texture unit.

• _sampler -

  Program sampler.

• _handle -

  Frame buffer handle.

• _attachment -

  Frame buffer attachment index.

• _access -

  Texture access. See Access::Enum.

• _format -

  Texture format. See: TextureFormat::Enum.

Dispatch¶

uint32_t bgfx::dispatch(uint8_t _id, ProgramHandle _handle, uint16_t _numX, uint16_t _numY, uint16_t _numZ, uint8_t _flags)¶

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.

uint32_t bgfx::dispatch(uint8_t _id, ProgramHandle _handle, IndirectBufferHandle _indirectHandle, uint16_t _start, uint16_t _num, uint8_t _flags)¶

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.

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, uint16_t _max)¶

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::destroyShader(ShaderHandle _handle)¶

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

Attention

C99 equivalent is bgfx_destroy_shader.

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

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

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::destroyProgram(ProgramHandle _handle)¶

Destroy program.

Attention

C99 equivalent is bgfx_destroy_program.

Uniforms¶

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

Create shader uniform parameter.

Return

Handle to uniform object.

Remark

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::destroyUniform(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¶

End¶

Vec4¶

Mat3¶

Mat4¶

Count¶

Vertex Buffers¶

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

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::destroyVertexBuffer(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)¶

Start VertexDecl.

Attention

C99 equivalent is bgfx_vertex_decl_begin.

void end()¶

End VertexDecl.

Attention

C99 equivalent is bgfx_vertex_decl_begin.

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

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

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

Create empty dynamic vertex buffer.

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

Create dynamic vertex buffer and initialize it.

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::destroyDynamicVertexBuffer(DynamicVertexBufferHandle _handle)¶

Destroy dynamic vertex buffer.

Attention

C99 equivalent is bgfx_destroy_dynamic_vertex_buffer.

bool bgfx::checkAvailTransientVertexBuffer(uint32_t _num, const VertexDecl &_decl)¶

Returns true if internal transient vertex buffer has enough space.

Attention

C99 equivalent is bgfx_check_avail_transient_vertex_buffer.

Parameters

• _num -

  Number of vertices.

• _decl -

  Vertex declaration.

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

Allocate transient vertex buffer.

Remark

You must call setVertexBuffer after alloc in order to avoid memory leak.

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

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

Destroy static index buffer.

Attention

C99 equivalent is bgfx_destroy_index_buffer.

DynamicIndexBufferHandle bgfx::createDynamicIndexBuffer(uint32_t _num, uint16_t _flags)¶

Create empty dynamic index buffer.

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

Create dynamic index buffer and initialized it.

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::destroyDynamicIndexBuffer(DynamicIndexBufferHandle _handle)¶

Destroy dynamic index buffer.

Attention

C99 equivalent is bgfx_destroy_dynamic_index_buffer.

Parameters

• _handle -

  Dynamic index buffer handle.

bool bgfx::checkAvailTransientIndexBuffer(uint32_t _num)¶

Returns true if internal transient index buffer has enough space.

Attention

C99 equivalent is bgfx_check_avail_transient_index_buffer.

Parameters

• _num -

  Number of indices.

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

Allocate transient index buffer.

Remark

1. You must call setIndexBuffer after alloc in order to avoid memory leak.
2. 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).

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¶

RGB9E5F¶

BGRA8¶

RGBA8¶

RGBA8I¶

RGBA8U¶

RGBA8S¶

RGBA16¶

RGBA16I¶

RGBA16U¶

RGBA16F¶

RGBA16S¶

RGBA32I¶

RGBA32U¶

RGBA32F¶

R5G6B5¶

RGBA4¶

RGB5A1¶

RGB10A2¶

R11G11B10F¶

UnknownDepth¶

D16¶

D24¶

D24S8¶

D32¶

D16F¶

D24F¶

D32F¶

D0S8¶

Count¶

void bgfx::calcTextureSize(TextureInfo &_info, uint16_t _width, uint16_t _height, uint16_t _depth, bool _cubeMap, uint8_t _numMips, TextureFormat::Enum _format)¶

Calculate amount of memory required for texture.

Attention

C99 equivalent is bgfx_calc_texture_size.

TextureHandle bgfx::createTexture(const Memory *_mem, uint32_t _flags, uint8_t _skip, TextureInfo *_info)¶

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, uint8_t _numMips, TextureFormat::Enum _format, uint32_t _flags, const Memory *_mem)¶

Create 2D texture.

Attention

C99 equivalent is bgfx_create_texture_2d.

Parameters

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

• _mem -

  Texture data. If _mem is non-NULL, created texture will be immutable.

TextureHandle bgfx::createTexture2D(BackbufferRatio::Enum _ratio, uint8_t _numMips, TextureFormat::Enum _format, uint32_t _flags)¶

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.

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

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

Update 2D texture.

Attention

C99 equivalent is bgfx_update_texture_2d.

Parameters

• _handle -

  Texture handle.

• _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, uint8_t _numMips, TextureFormat::Enum _format, uint32_t _flags, const Memory *_mem)¶

Create 3D texture.

Attention

C99 equivalent is bgfx_create_texture_3d.

Parameters

• _width -

  Width.

• _height -

  Height.

• _depth -

  Depth.

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

• _mem -

  Texture data. If _mem is non-NULL, created texture will be immutable.

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, uint8_t _numMips, TextureFormat::Enum _format, uint32_t _flags, const Memory *_mem)¶

Create Cube texture.

Attention

C99 equivalent is bgfx_create_texture_cube.

Parameters

• _size -

  Cube side size.

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

• _mem -

  Texture data. If _mem is non-NULL, created texture will be immutable.

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

Update Cube texture.

Attention

C99 equivalent is bgfx_update_texture_cube.

Parameters

• _handle -

  Texture handle.

• _side -

  Cubemap side, 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.

void bgfx::readTexture(TextureHandle _handle, void *_data)¶

Read back texture content.

Attention

Texture must be created with BGFX_TEXTURE_READ_BACK flag.

Availability depends on: BGFX_CAPS_TEXTURE_READ_BACK.

C99 equivalent is bgfx_read_texture.

Parameters

• _handle -

  Texture handle.

• _data -

  Destination buffer.

void bgfx::readTexture(FrameBufferHandle _handle, uint8_t _attachment, void *_data)¶

Read back texture content.

Attention

Texture must be created with BGFX_TEXTURE_READ_BACK flag.

Availability depends on: BGFX_CAPS_TEXTURE_READ_BACK.

C99 equivalent is bgfx_read_texture.

Parameters

• _handle -

  Frame buffer handle.

• _attachment -

  Frame buffer attachment index.

• _data -

  Destination buffer.

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

Create frame buffer (simple).

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

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

Create frame buffer.

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

Create frame buffer for multiple window rendering.

Return

Handle to frame buffer object.

Remark

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

void bgfx::destroyFrameBuffer(FrameBufferHandle _handle)¶

Destroy frame buffer.

Attention

C99 equivalent is bgfx_destroy_frame_buffer.

Instance Buffer¶

bool bgfx::checkAvailInstanceDataBuffer(uint32_t _num, uint16_t _stride)¶

Returns true if internal instance data buffer has enough space.

Attention

C99 equivalent is bgfx_check_avail_instance_data_buffer.

Parameters

• _num -

  Number of instances.

• _stride -

  Stride per instance.

const InstanceDataBuffer *bgfx::allocInstanceDataBuffer(uint32_t _num, uint16_t _stride)¶

Allocate instance data buffer.

Remark

You must call setInstanceDataBuffer after alloc in order to avoid memory leak.

Attention

C99 equivalent is bgfx_alloc_instance_data_buffer.

Indirect Buffer¶

IndirectBufferHandle bgfx::createIndirectBuffer(uint32_t _num)¶

Create draw indirect buffer.

Attention

C99 equivalent is bgfx_create_indirect_buffer.

void bgfx::destroyIndirectBuffer(IndirectBufferHandle _handle)¶

Destroy draw indirect buffer.

Attention

C99 equivalent is bgfx_destroy_indirect_buffer.