API Reference
Note
If you’re just getting started with bgfx, you might get more out of these simple walkthroughs for how to use bgfx’s API:
General
General API for initialization, shutdown, frame management, debug, and querying renderer information.
Initialization and Shutdown
-
BGFX_DIAGNOSTIC_NONE
No diagnostics.
-
BGFX_DIAGNOSTIC_VERBOSE
Report informational debug layer messages, not only warnings and errors. Requires
Init::debug.
-
BGFX_DIAGNOSTIC_GPU_VALIDATION
Enable GPU-based validation (D3D12 GPU-based validation, Vulkan GPU-assisted validation). Requires
Init::debug.
-
BGFX_DIAGNOSTIC_SYNC_VALIDATION
Enable queue synchronization validation (D3D12 synchronized command queue validation, Vulkan synchronization validation). Requires
Init::debug.
-
BGFX_DIAGNOSTIC_SERIALIZE
Wait for the GPU to finish each submitted command buffer before recording the next one.
-
BGFX_PCI_ID_NONE
Autoselect adapter.
-
BGFX_PCI_ID_SOFTWARE_RASTERIZER
Software rasterizer.
-
BGFX_PCI_ID_AMD
AMD adapter.
-
BGFX_PCI_ID_APPLE
Apple adapter.
-
BGFX_PCI_ID_ARM
ARM adapter.
-
BGFX_PCI_ID_GOOGLE
Google adapter.
-
BGFX_PCI_ID_INTEL
Intel adapter.
-
BGFX_PCI_ID_MICROSOFT
Microsoft adapter.
-
BGFX_PCI_ID_NVIDIA
NVIDIA adapter.
-
struct Init
Initialization parameters used by
bgfx::init.- Attention
C99’s equivalent binding is
bgfx_init_t.
Public Members
-
RendererType::Enum type
Select rendering backend. When set to RendererType::Count a default rendering backend will be selected appropriate to the platform. See:
bgfx::RendererType
-
RendererType::Enum backendType
Select native API a layered rendering backend (WebGPU) runs on. When set to RendererType::Count implementation’s default will be selected.
-
uint16_t vendorId
Vendor PCI ID. If set to
BGFX_PCI_ID_NONE, discrete and integrated GPUs will be prioritised.BGFX_PCI_ID_NONE- Autoselect adapter.BGFX_PCI_ID_SOFTWARE_RASTERIZER- Software rasterizer.BGFX_PCI_ID_AMD- AMD adapter.BGFX_PCI_ID_APPLE- Apple adapter.BGFX_PCI_ID_INTEL- Intel adapter.BGFX_PCI_ID_NVIDIA- NVIDIA adapter.BGFX_PCI_ID_MICROSOFT- Microsoft adapter.
-
uint16_t deviceId
Device ID. If set to 0 it will select first device, or device with matching ID.
-
uint64_t capabilities
Capabilities initialization mask (default: UINT64_MAX).
-
bool debug
Enable device for debugging.
-
uint32_t diagnostics
Diagnostic flags. See:
BGFX_DIAGNOSTIC_*.
-
bool profile
Enable device for profiling.
-
bool fallback
Enable fallback to next available renderer.
-
bool videoDecode
Enable video decoding.
-
PlatformData platformData
Platform data.
-
SwapChain swapChain
Swap chain for the window bgfx creates its device on. See:
bgfx::SwapChain.
-
uint32_t reset
Device and frame global settings. Anything that is a property of one surface belongs in
swapChaininstead. See:BGFX_RESET_*.
-
CallbackI *callback
Provide application specific callback interface. See:
bgfx::CallbackI
-
bx::AllocatorI *allocator
Custom allocator. When a custom allocator is not specified, bgfx uses the CRT allocator. Bgfx assumes custom allocator is thread safe.
-
struct Limits
Public Members
-
uint16_t maxEncoders
Maximum number of encoder threads.
-
uint32_t numDrawCalls
Number of draw calls per frame to reserve storage for. Rounded up to a multiple of
BGFX_CONFIG_DRAW_CALL_BLOCK, which is also the minimum. This is a reservation, not a limit: submitting more than this grows the storage during the frame, up toBGFX_CONFIG_MAX_DRAW_CALLS. WithBGFX_CONFIG_DYNAMIC_FRAME_STORAGEdisabled nothing grows, and this is a hard limit thatCaps::Limits::maxDrawCallsreports back; submissions past it are dropped. SeeStats::numDrawCallsPeakto size it.
-
uint32_t numDrawCallPeakFrames
Number of frames the draw-call peak (high-water mark) is observed before unused storage is released. Also used for view storage, resource command buffers and uniform buffers. Set to 0 to keep whatever has been allocated for the lifetime of the context. With
BGFX_CONFIG_DYNAMIC_FRAME_STORAGEdisabled draw/blit/rect storage is not resized; unused uniform and resource command buffer space is still released.
-
uint32_t minViews
Minimum number of views to keep state for. Rounded up to a multiple of 64. This is a reservation, not a limit: a view past it gets storage when it is first set, up to
Caps::Limits::maxViews, and that storage is released again once the views sharing it are all reset. Per-frame view data is sized by the views used in a frame, seenumDrawCallPeakFrames. WithBGFX_CONFIG_DYNAMIC_FRAME_STORAGEdisabled storage for all views is allocated up front.
-
uint32_t minResourceCbSize
Minimum resource command buffer size.
-
uint32_t maxTransientVbSize
Maximum transient vertex buffer size.
-
uint32_t maxTransientIbSize
Maximum transient index buffer size.
-
uint32_t minUniformBufferSize
Mimimum uniform buffer size.
-
uint32_t minUniformCacheSize
Minimum view and frame uniform cache size. This is a reservation, the cache grows on demand.
-
uint16_t maxEncoders
-
bool bgfx::init(const Init &_init)
Initialize the bgfx library.
- Attention
C99’s equivalent binding is
bgfx_init.
- Parameters:
_init – [in] Initialization parameters. See:
bgfx::Initfor more info.- Returns:
trueif initialization was successful.
-
void bgfx::shutdown()
Shutdown bgfx library.
- Attention
C99’s equivalent binding is
bgfx_shutdown.
Updating
Reset
Reset flags control back-buffer resolution, MSAA, vsync, and other global rendering settings.
-
BGFX_RESET_NONE
No reset flags.
-
BGFX_RESET_FULLSCREEN
Not supported yet.
-
BGFX_RESET_VSYNC
Enable V-Sync.
-
BGFX_RESET_MAXANISOTROPY
Turn on/off max anisotropy.
-
BGFX_RESET_CAPTURE
Begin screen capture.
-
BGFX_RESET_FLUSH_AFTER_RENDER
Flush rendering after submitting to GPU.
-
BGFX_RESET_FLIP_AFTER_RENDER
This flag specifies where flip occurs. Default behaviour is that flip occurs before rendering new frame. This flag only has effect when
BGFX_CONFIG_MULTITHREADED=0.
-
BGFX_RESET_SRGB_BACKBUFFER
Enable sRGB backbuffer.
-
BGFX_RESET_HDR10
Enable HDR10 rendering.
-
BGFX_RESET_HIDPI
Enable HiDPI rendering.
-
BGFX_RESET_SUSPEND
Suspend rendering.
-
BGFX_RESET_TRANSPARENT_BACKBUFFER
Transparent backbuffer. Availability depends on:
BGFX_CAPS_TRANSPARENT_BACKBUFFER.
-
BGFX_RESET_LOW_LATENCY_ON
Enable low latency mode (NVIDIA Reflex). Availability depends on:
BGFX_CAPS_LOW_LATENCY.
-
BGFX_RESET_LOW_LATENCY_BOOST
Enable low latency mode, and keep GPU clocks high even when GPU is mostly idle. Availability depends on:
BGFX_CAPS_LOW_LATENCY.
-
void bgfx::reset(uint32_t _flags = BGFX_RESET_NONE, const SwapChain *_swapChain = NULL)
Reset graphic settings and back-buffer size.
- Attention
This call doesn’t change the window size, it just resizes the back-buffer. Your windowing code controls the window size.
- Attention
C99’s equivalent binding is
bgfx_reset.
- Parameters:
_flags – [in] See:
BGFX_RESET_*for more info.BGFX_RESET_NONE- No reset flags.BGFX_RESET_VSYNC- Enable V-Sync.BGFX_RESET_MAXANISOTROPY- Turn on/off max anisotropy.BGFX_RESET_CAPTURE- Begin screen capture.BGFX_RESET_FLUSH_AFTER_RENDER- Flush rendering after submitting to GPU.BGFX_RESET_FLIP_AFTER_RENDER- This flag specifies where flip occurs. Default behaviour is that flip occurs before rendering new frame. This flag only has effect whenBGFX_CONFIG_MULTITHREADED=0.BGFX_RESET_LOW_LATENCY_ON- Enable low latency mode (NVIDIA Reflex). Availability depends on:BGFX_CAPS_LOW_LATENCY.BGFX_RESET_LOW_LATENCY_BOOST- Enable low latency mode, and keep GPU clocks high even when GPU is mostly idle. Availability depends on:BGFX_CAPS_LOW_LATENCY. Set eitherBGFX_RESET_LOW_LATENCY_ONorBGFX_RESET_LOW_LATENCY_BOOST, not both. Per-surface settings are not here.BGFX_SWAP_CHAIN_*flags belong onSwapChain::flags, and are ignored if passed here.
_swapChain – [in] Main window swap chain. When
NULLthe main window is left untouched and only the device and frame globals above are applied, which is what an application driving its own swap chains wants. Otherwise the main window takes on this description: resize it, change its format, or change its per-surface flags. Fields left neutral keep their current value. A newnwhmoves the main window to another native window: the renderer recreates the main swap chain for it and keeps the device, context and every GPU resource.ndtmust stay whatbgfx::initreceived. Must beNULLwhenbgfx::initcreated no main window.
Swap Chain
Swap chain flags control properties of a single presentation surface. They are numerically
identical to their BGFX_RESET_* counterparts, so main’s flags round-trip losslessly.
-
BGFX_SWAP_CHAIN_NONE
No swap chain flags.
-
BGFX_SWAP_CHAIN_FULLSCREEN
Not supported yet.
-
BGFX_SWAP_CHAIN_SRGB_BACKBUFFER
Enable sRGB backbuffer.
-
BGFX_SWAP_CHAIN_HDR10
Enable HDR10 rendering.
-
BGFX_SWAP_CHAIN_HIDPI
Enable HiDPI rendering.
-
BGFX_SWAP_CHAIN_TRANSPARENT_BACKBUFFER
Transparent backbuffer. Availability depends on:
BGFX_CAPS_TRANSPARENT_BACKBUFFER.
-
struct SwapChain
Swap chain description.
- Attention
C99’s equivalent binding is
bgfx_swap_chain_t.
Public Members
-
void *nwh
Native window handle. If
NULL, bgfx will create a headless context/device, provided the rendering API supports it.
-
void *ndt
Native display type (*nix specific). A window that leaves this
NULLuses the one the main window was initialized with.
-
uint32_t width
Swap chain width.
-
uint32_t height
Swap chain height.
-
uint32_t flags
See:
BGFX_SWAP_CHAIN_*.
-
TextureFormat::Enum formatColor
Color format.
-
TextureFormat::Enum formatDepthStencil
Depth/stencil format, or
TextureFormat::Countfor no depth. Ignored whendepthis valid.
-
TextureHandle depth
Depth attachment. Must be created with
BGFX_TEXTURE_RT, and match the swap chain width, height and sample count. When invalid, bgfx creates and owns a depth surface performatDepthStencil. A texture supplied here is never destroyed by bgfx, and may be shared by several same-size swap chains.
-
uint8_t numBackBuffers
Number of back buffers.
-
uint8_t maxFrameLatency
Maximum frame latency.
-
FrameBufferHandle bgfx::createFrameBuffer(const SwapChain &_desc)
Create a frame buffer for a window, from a full swap chain description.
Remark
Frame buffer cannot be used for sampling.
- Attention
Availability depends on:
BGFX_CAPS_SWAP_CHAIN.- Attention
C99’s equivalent binding is
bgfx_create_frame_buffer_from_swap_chain.
- Parameters:
_desc – [in] Swap chain description. See:
bgfx::SwapChain.- Returns:
Frame buffer handle.
-
void bgfx::updateSwapChain(FrameBufferHandle _handle, const SwapChain &_desc)
Change a swap chain’s size, format or per-surface flags, in place.
The frame buffer handle stays valid, so nothing that refers to it has to be rebuilt. Pass
BGFX_INVALID_HANDLEto address the window bgfx was initialized with.- Attention
Availability depends on:
BGFX_CAPS_SWAP_CHAIN.- Attention
C99’s equivalent binding is
bgfx_update_swap_chain.
- Parameters:
_handle – [in] Window frame buffer handle. The window bgfx was initialized with is not addressed here; it is
bgfx::reset’s swap chain._desc – [in] Swap chain description. See:
bgfx::SwapChain.
Frame
Frame flags and the bgfx::frame call to advance to the next frame.
-
BGFX_FRAME_NONE
No frame flags.
-
BGFX_FRAME_DEBUG_CAPTURE
Capture frame with graphics debugger.
-
BGFX_FRAME_DISCARD
Discard all draw calls.
-
BGFX_FRAME_FLUSH
Execute all rendering commands without presenting the backbuffer.
-
uint32_t bgfx::frame(uint8_t _flags = BGFX_FRAME_NONE)
Advance to next frame. This is the main frame-advancement call on the API thread (the thread from which
bgfx::initwas called).Multithreaded renderer (
BGFX_CONFIG_MULTITHREADED=1, default): This call waits for the render thread to finish processing the previous frame, then swaps internal submit/render buffers, signals the render thread to begin processing the new frame viabgfx::renderFrame, and returns immediately. The render thread and API thread then run in parallel: the API thread builds the next frame while the render thread executes GPU commands for the current frame.Single-threaded renderer (
BGFX_CONFIG_MULTITHREADED=0, or whenbgfx::renderFrameandbgfx::initare called from the same thread): This call swaps internal buffers and performs frame rendering inline (internally callsbgfx::renderFrame), then returns.Remark
Must be called from the API thread (the thread that called
bgfx::init). In multithreaded mode, this call synchronizes withbgfx::renderFramerunning on the render thread via semaphores:bgfx::framewaits for the render thread to finish, then posts a signal thatbgfx::renderFramewaits on to begin the next frame. See also:bgfx::renderFrame.- Attention
C99’s equivalent binding is
bgfx_frame.
- Parameters:
_flags – [in] Frame flags. See:
BGFX_FRAME_*for more info.BGFX_FRAME_NONE- No frame flag.BGFX_FRAME_DEBUG_CAPTURE- Capture frame with graphics debugger.BGFX_FRAME_DISCARD- Discard all draw calls.BGFX_FRAME_FLUSH- Execute all rendering commands without presenting the backbuffer.
- Returns:
Current frame number. This might be used in conjunction with double/multi buffering data outside the library and passing it to library via
bgfx::makeRefcalls.
Debug
Debug Features
Enable or disable debug features.
-
void bgfx::setDebug(uint32_t _debug, FrameBufferHandle _handle = BGFX_INVALID_HANDLE, uint8_t _scale = 0)
Set debug flags.
- Attention
C99’s equivalent binding is
bgfx_set_debug.
- Parameters:
_debug – [in] Available flags:
BGFX_DEBUG_IFH- Infinitely fast hardware. When this flag is set all rendering calls will be skipped. This is useful when profiling to quickly assess potential bottlenecks between CPU and GPU.BGFX_DEBUG_PROFILER- Enable profiler.BGFX_DEBUG_STATS- Display internal statistics.BGFX_DEBUG_TEXT- Display debug text.BGFX_DEBUG_WIREFRAME- Wireframe rendering. All rendering primitives will be rendered as lines.
_handle – [in] Frame buffer the debug text and statistics are drawn on. Invalid handle selects the window bgfx was initialized with.
_scale – [in] Debug text scale factor. 0 is the same as 1.
Debug Flags
Flags for bgfx::setDebug.
-
BGFX_DEBUG_NONE
No debug.
-
BGFX_DEBUG_WIREFRAME
Enable wireframe for all primitives.
-
BGFX_DEBUG_IFH
Enable infinitely fast hardware test. No draw calls will be submitted to driver. It’s useful when profiling to quickly assess bottleneck between CPU and GPU.
-
BGFX_DEBUG_STATS
Enable statistics display.
-
BGFX_DEBUG_TEXT
Enable debug text display.
-
BGFX_DEBUG_PROFILER
Enable profiler. This causes per-view statistics to be collected, available through
bgfx::Stats::ViewStats. This is unrelated to the profiler functions inbgfx::CallbackI.
Debug Text Display
Functions for printing debug text on screen.
-
void bgfx::dbgTextClear(uint8_t _attr = 0, bool _small = false)
Clear internal debug text buffer.
- Attention
C99’s equivalent binding is
bgfx_dbg_text_clear.
- Parameters:
_attr – [in] Background color.
_small – [in] Default 8x16 or 8x8 font.
-
void bgfx::dbgTextPrintf(uint16_t _x, uint16_t _y, uint8_t _attr, const char *_format, ...)
Print formatted data to internal debug text character-buffer (VGA-compatible text mode).
- Attention
C99’s equivalent binding is
bgfx_dbg_text_printf.
- Parameters:
_x – [in] Position x from the left corner of the window.
_y – [in] Position y from the top corner of the window.
_attr – [in] Color palette. Where top 4-bits represent index of background, and bottom 4-bits represent foreground color from standard VGA text palette (ANSI escape codes).
_format – [in]
printfstyle format.
- Param :
-
void bgfx::dbgTextPrintfVargs(uint16_t _x, uint16_t _y, uint8_t _attr, const char *_format, va_list _argList)
Print formatted data from variable argument list to internal debug text character-buffer (VGA-compatible text mode).
- Attention
C99’s equivalent binding is
bgfx_dbg_text_vprintf.
- Parameters:
_x – [in] Position x from the left corner of the window.
_y – [in] Position y from the top corner of the window.
_attr – [in] Color palette. Where top 4-bits represent index of background, and bottom 4-bits represent foreground color from standard VGA text palette (ANSI escape codes).
_format – [in]
printfstyle format._argList – [in] Variable arguments list for format string.
-
void bgfx::dbgTextImage(uint16_t _x, uint16_t _y, uint16_t _width, uint16_t _height, const void *_data, uint16_t _pitch)
Draw image into internal debug text buffer.
- Attention
C99’s equivalent binding is
bgfx_dbg_text_image.
- Parameters:
_x – [in] Position x from the left corner of the window.
_y – [in] Position y from the top corner of the window.
_width – [in] Image width.
_height – [in] Image height.
_data – [in] Raw image data (character/attribute raw encoding).
_pitch – [in] Image pitch in bytes.
Querying information
Renderer
Query the active rendering backend.
-
struct RendererType
Renderer backend type enum.
- Attention
C99’s equivalent binding is
bgfx_renderer_type_t.
Public Types
-
enum Enum
Renderer types:
Values:
-
enumerator Noop
No rendering.
-
enumerator Agc
AGC.
-
enumerator Direct3D11
Direct3D 11.0.
-
enumerator Direct3D12
Direct3D 12.0.
-
enumerator Gnm
GNM.
-
enumerator Metal
Metal.
-
enumerator Nvn
NVN.
-
enumerator OpenGLES
OpenGL ES 3.0+.
-
enumerator OpenGL
OpenGL 4.3+.
-
enumerator Vulkan
Vulkan.
-
enumerator WebGPU
WebGPU.
-
enumerator Count
-
enumerator Noop
-
uint8_t bgfx::getSupportedRenderers(uint8_t _max = 0, RendererType::Enum *_enum = NULL)
Returns supported backend API renderers.
- Attention
C99’s equivalent binding is
bgfx_get_supported_renderers.
- Parameters:
_max – [in] Maximum number of elements in _enum array.
_enum – [inout] Array where supported renderers will be written.
- Returns:
Number of supported renderers.
-
RendererType::Enum bgfx::getRendererType()
Returns current renderer backend API type.
Remark
Library must be initialized.
- Attention
C99’s equivalent binding is
bgfx_get_renderer_type.
- Returns:
Renderer backend type. See:
bgfx::RendererType
Capabilities
Query GPU capabilities and limits.
Available Caps
Individual capability flags.
-
BGFX_CAPS_BLEND_INDEPENDENT
Blend independent is supported.
-
BGFX_CAPS_COMPUTE
Compute shaders are supported.
-
BGFX_CAPS_CONSERVATIVE_RASTER
Conservative rasterization is supported.
-
BGFX_CAPS_DRAW_INDIRECT
Draw indirect is supported.
-
BGFX_CAPS_DRAW_INDIRECT_COUNT
Draw indirect with indirect count is supported.
-
BGFX_CAPS_FRAGMENT_ORDERING
Fragment ordering is available in fragment shader.
-
BGFX_CAPS_GRAPHICS_DEBUGGER
Graphics debugger is present.
-
BGFX_CAPS_HDR10
HDR10 rendering is supported.
-
BGFX_CAPS_IMAGE_RW
Image Read/Write is supported.
-
BGFX_CAPS_INDEX32
32-bit indices are supported.
-
BGFX_CAPS_LOW_LATENCY
Low latency mode (NVIDIA Reflex) is supported.
-
BGFX_CAPS_PRIMITIVE_ID
PrimitiveID is available in fragment shader.
-
BGFX_CAPS_RENDERER_MULTITHREADED
Renderer is on separate thread.
-
BGFX_CAPS_SHADER_F16
16-bit floats are supported in shaders.
-
BGFX_CAPS_SWAP_CHAIN
Multiple windows are supported.
-
BGFX_CAPS_TEXTURE_CUBE_ARRAY
Cubemap texture array is supported.
-
BGFX_CAPS_TEXTURE_DIRECT_ACCESS
CPU direct access to GPU texture memory.
-
BGFX_CAPS_TEXTURE_EXTERNAL
External texture is supported.
-
BGFX_CAPS_TEXTURE_EXTERNAL_SHARED
External shared texture is supported.
-
BGFX_CAPS_TRANSPARENT_BACKBUFFER
Transparent back buffer supported.
-
BGFX_CAPS_VARIABLE_RATE_SHADING
Variable Rate Shading.
-
BGFX_CAPS_VERTEX_ATTRIB_UINT10
Vertex attribute 10_10_10_2 is supported.
-
BGFX_CAPS_VIDEO_DECODE
Hardware video decode is supported.
-
BGFX_CAPS_VIEWPORT_LAYER_ARRAY
Viewport layer is available in vertex shader.
Statistics
Per-frame rendering statistics.
-
struct ViewStats
View stats.
- Attention
C99’s equivalent binding is
bgfx_view_stats_t.
-
struct Stats
Renderer statistics data.
Remark
All time values are high-resolution timestamps, while time frequencies define timestamps-per-second for that hardware.
- Attention
C99’s equivalent binding is
bgfx_stats_t.
Public Members
-
int64_t cpuTimeFrame
CPU time between two
bgfx::framecalls.
-
int64_t cpuTimeBegin
Render thread CPU submit begin time.
-
int64_t cpuTimeEnd
Render thread CPU submit end time.
-
int64_t cpuTimerFreq
CPU timer frequency. Timestamps-per-second.
-
int64_t gpuTimeBegin
GPU frame begin time.
-
int64_t gpuTimeEnd
GPU frame end time.
-
int64_t gpuTimerFreq
GPU timer frequency.
-
int64_t waitRender
Time spent waiting for render backend thread to finish issuing draw commands to underlying graphics API.
-
int64_t waitSubmit
Time spent waiting for submit thread to advance to next frame.
-
int64_t latencySleep
Time
bgfx::frameslept in low latency mode.
-
int64_t latencyTotal
Time from simulation start until GPU finished the frame.
-
int64_t latencySimulation
Simulation, API thread time between
bgfx::framecalls.
-
int64_t latencyRenderSubmit
Render thread time issuing the frame to the graphics API.
-
int64_t latencyPresent
Time spent in present.
-
int64_t latencyQueue
Time between present and GPU starting the frame.
-
int64_t latencyGpu
GPU time from start to end of the frame.
-
uint32_t numDraw
Number of draw calls submitted.
-
uint32_t numCompute
Number of compute calls submitted.
-
uint32_t numBlit
Number of blit calls submitted.
-
uint32_t numBlitRepack
Number of buffer to texture blit calls that had to be repacked, because
BufferRegion::rowPitchoroffsetdidn’t matchCaps::Limits::blitRowPitchAlignorblitOffsetAlign.
-
uint32_t numDrawCallsPeak
Highest number of draw+compute calls requested in a single frame so far (peak demand, before any were dropped). Useful to tune
Init::Limits::numDrawCalls.
-
uint32_t maxGpuLatency
GPU driver latency.
-
uint32_t gpuFrameNum
Frame which generated gpuTimeBegin, gpuTimeEnd.
-
uint16_t numDynamicIndexBuffers
Number of used dynamic index buffers.
-
uint16_t numDynamicVertexBuffers
Number of used dynamic vertex buffers.
-
uint16_t numFrameBuffers
Number of used frame buffers.
-
uint16_t numIndexBuffers
Number of used index buffers.
-
uint16_t numOcclusionQueries
Number of used occlusion queries.
-
uint16_t numPrograms
Number of used programs.
-
uint16_t numShaders
Number of used shaders.
-
uint16_t numTextures
Number of used textures.
-
uint16_t numUniforms
Number of used uniforms.
-
uint16_t numVertexBuffers
Number of used vertex buffers.
-
uint16_t numVertexLayouts
Number of used vertex layouts.
-
int64_t textureMemoryUsed
Estimate of texture memory used.
-
int64_t rtMemoryUsed
Estimate of render target memory used.
-
int32_t transientVbUsed
Amount of transient vertex buffer used.
-
int32_t transientIbUsed
Amount of transient index buffer used.
-
uint32_t numPrims[Topology::Count]
Number of primitives rendered.
-
int64_t gpuMemoryMax
Maximum available GPU memory for application.
-
int64_t gpuMemoryUsed
Amount of GPU memory used by the application.
-
uint16_t width
Backbuffer width in pixels.
-
uint16_t height
Backbuffer height in pixels.
-
uint16_t textWidth
Debug text width in characters.
-
uint16_t textHeight
Debug text height in characters.
-
uint16_t numViews
Number of view stats.
-
uint8_t numEncoders
Number of encoders used during frame.
-
EncoderStats *encoderStats
Array of encoder stats.
-
const Stats *bgfx::getStats()
Returns performance counters.
- Attention
Pointer returned is valid until
bgfx::frameis called.- Attention
C99’s equivalent binding is
bgfx_get_stats.
- Returns:
Performance counters.
Platform specific
These are platform specific APIs. It is only necessary to use these APIs in conjunction with creating windows.
-
struct RenderFrame
Render frame enum.
- Attention
C99’s equivalent binding is
bgfx_render_frame_t.
-
struct InternalData
Internal data.
- Attention
C99’s equivalent binding is
bgfx_internal_data_t.
-
struct PlatformData
Platform data.
- Attention
C99’s equivalent binding is
bgfx_platform_data_t.
-
RenderFrame::Enum bgfx::renderFrame(int32_t _msecs = -1)
Render frame. Executes the actual GPU rendering work for one frame.
In the default multithreaded configuration,
bgfx::renderFrameruns on the render thread whilebgfx::frameruns on the API thread. Their interaction is as follows:The render thread calls
bgfx::renderFrame, which blocks waiting for the API thread to signal that a new frame is ready.On the API thread,
bgfx::framefinishes building the frame, swaps internal submit/render buffers, and signals the render thread.bgfx::renderFramewakes up, executes pre-render commands, submits GPU draw calls, executes post-render commands, flips the back buffer, then signals back to the API thread that rendering is complete.The API thread’s next
bgfx::framecall waits for this completion signal before swapping buffers again.
This double-buffered semaphore handshake allows the API thread and render thread to run in parallel, overlapping CPU frame building with GPU rendering.
- Attention
bgfx::renderFrameis a blocking call. It waits forbgfx::frameto be called from the API thread to process the frame. If a timeout value is passed, the call will returnRenderFrame::Timeouteven ifbgfx::framehas not been called. A value of -1 (default) means wait indefinitely (up toBGFX_CONFIG_API_SEMAPHORE_TIMEOUT).- Attention
C99’s equivalent binding is
bgfx_render_frame.
Warning
This call should only be used on platforms that don’t allow creating a separate rendering thread. If it is called before
bgfx::init, the internal render thread won’t be created by thebgfx::initcall, and the user is responsible for callingbgfx::renderFrameon the render thread each frame. If bothbgfx::renderFrameandbgfx::initare called from the same thread, bgfx operates in single-threaded mode andbgfx::framewill internally invokebgfx::renderFrameautomatically. See also:bgfx::frame.- Parameters:
_msecs – [in] Timeout in milliseconds.
- Returns:
Current renderer context state. See:
bgfx::RenderFrame.
-
const InternalData *bgfx::getInternalData()
Get internal data for interop.
- Attention
It’s expected you understand some bgfx internals before you use this call.
- Attention
C99’s equivalent binding is
bgfx_get_internal_data.
Warning
Must be called only on render thread.
- Returns:
Internal data.
Miscellaneous
-
struct TopologyConvert
Topology conversion function.
- Attention
C99’s equivalent binding is
bgfx_topology_convert_t.
Public Types
-
enum Enum
Topology conversion functions:
Values:
-
enumerator TriListFlipWinding
Flip winding order of triangle list.
-
enumerator TriStripFlipWinding
Flip winding order of triangle strip.
-
enumerator TriListToLineList
Convert triangle list to line list.
-
enumerator TriStripToTriList
Convert triangle strip to triangle list.
-
enumerator LineStripToLineList
Convert line strip to line list.
-
enumerator Count
-
enumerator TriListFlipWinding
-
struct TopologySort
Topology sort order.
- Attention
C99’s equivalent binding is
bgfx_topology_sort_t.
Public Types
-
enum Enum
Topology sort order:
Values:
-
enumerator DirectionFrontToBackMin
-
enumerator DirectionFrontToBackAvg
-
enumerator DirectionFrontToBackMax
-
enumerator DirectionBackToFrontMin
-
enumerator DirectionBackToFrontAvg
-
enumerator DirectionBackToFrontMax
-
enumerator DistanceFrontToBackMin
-
enumerator DistanceFrontToBackAvg
-
enumerator DistanceFrontToBackMax
-
enumerator DistanceBackToFrontMin
-
enumerator DistanceBackToFrontAvg
-
enumerator DistanceBackToFrontMax
-
enumerator Count
-
enumerator DirectionFrontToBackMin
-
void bgfx::vertexPack(const float _input[4], bool _inputNormalized, Attrib::Enum _attr, const VertexLayout &_layout, void *_data, uint32_t _index = 0)
Pack vertex attribute into vertex stream format.
- Attention
C99’s equivalent binding is
bgfx_vertex_pack.
- Parameters:
_input – [in] Value to be packed into vertex stream.
_inputNormalized – [in]
trueif input value is already normalized._attr – [in] Attribute to pack.
_layout – [in] Vertex stream layout.
_data – [in] Destination vertex stream where data will be packed.
_index – [in] Vertex index that will be modified.
-
void bgfx::vertexUnpack(float _output[4], Attrib::Enum _attr, const VertexLayout &_layout, const void *_data, uint32_t _index = 0)
Unpack vertex attribute from vertex stream format.
- Attention
C99’s equivalent binding is
bgfx_vertex_unpack.
- Parameters:
_output – [out] Result of unpacking.
_attr – [in] Attribute to unpack.
_layout – [in] Vertex stream layout.
_data – [in] Source vertex stream from where data will be unpacked.
_index – [in] Vertex index that will be unpacked.
-
void bgfx::vertexConvert(const VertexLayout &_dstLayout, void *_dstData, const VertexLayout &_srcLayout, const void *_srcData, uint32_t _num = 1)
Converts vertex stream data from one vertex stream format to another.
- Attention
C99’s equivalent binding is
bgfx_vertex_convert.
- Parameters:
_dstLayout – [in] Destination vertex stream layout.
_dstData – [in] Destination vertex stream.
_srcLayout – [in] Source vertex stream layout.
_srcData – [in] Source vertex stream data.
_num – [in] Number of vertices to convert from source to destination.
-
uint32_t bgfx::topologyConvert(TopologyConvert::Enum _conversion, void *_dst, uint32_t _dstSize, const void *_indices, uint32_t _numIndices, bool _index32)
Convert index buffer for use with different primitive topologies.
- Attention
C99’s equivalent binding is
bgfx_topology_convert.
- Parameters:
_conversion – [in] Conversion type, see
TopologyConvert::Enum._dst – [out] Destination index buffer. If this argument is NULL function will return number of indices after conversion.
_dstSize – [in] Destination index buffer in bytes. It must be large enough to contain output indices. If destination size is insufficient index buffer will be truncated.
_indices – [in] Source indices.
_numIndices – [in] Number of input indices.
_index32 – [in] Set to
trueif input indices are 32-bit.
- Returns:
Number of output indices after conversion.
-
void bgfx::topologySortTriList(TopologySort::Enum _sort, void *_dst, uint32_t _dstSize, const float _dir[3], const float _pos[3], const void *_vertices, uint32_t _stride, const void *_indices, uint32_t _numIndices, bool _index32)
Sort indices.
- Attention
C99’s equivalent binding is
bgfx_topology_sort_tri_list.
- Parameters:
_sort – [in] Sort order, see
TopologySort::Enum._dst – [out] Destination index buffer.
_dstSize – [in] Destination index buffer in bytes. It must be large enough to contain output indices. If destination size is insufficient index buffer will be truncated.
_dir – [in] Direction (vector must be normalized).
_pos – [in] Position.
_vertices – [in] Pointer to first vertex represented as float x, y, z. Must contain at least number of vertices referencende by index buffer.
_stride – [in] Vertex stride.
_indices – [in] Source indices.
_numIndices – [in] Number of input indices.
_index32 – [in] Set to
trueif input indices are 32-bit.
-
void bgfx::setPaletteColor(uint8_t _index, const float _rgba[4])
Set palette color value.
- Attention
C99’s equivalent binding is
bgfx_set_palette_color.
- Parameters:
_index – [in] Index into palette.
_rgba – [in] RGBA floating point values.
-
void bgfx::setPaletteColor(uint8_t _index, float _r, float _g, float _b, float _a)
Set palette color value.
- Attention
C99’s equivalent binding is
bgfx_set_palette_color_rgba32f.
- Parameters:
_index – [in] Index into palette.
_r – [in] Red value (RGBA floating point values)
_g – [in] Green value (RGBA floating point values)
_b – [in] Blue value (RGBA floating point values)
_a – [in] Alpha value (RGBA floating point values)
-
void bgfx::setPaletteColor(uint8_t _index, uint32_t _rgba)
Set palette color value.
- Attention
C99’s equivalent binding is
bgfx_set_palette_color_rgba8.
- Parameters:
_index – [in] Index into palette.
_rgba – [in] Packed 32-bit RGBA value.
-
void bgfx::requestScreenShot(FrameBufferHandle _handle, const char *_filePath)
Request screen shot of window back buffer.
Remark
bgfx::CallbackI::screenShotmust be implemented.- Attention
Frame buffer handle must be created with OS’ target native window handle.
- Attention
C99’s equivalent binding is
bgfx_request_screen_shot.
- Parameters:
_handle – [in] Frame buffer handle. If handle is
BGFX_INVALID_HANDLErequest will be made for main window back buffer._filePath – [in] Will be passed to
bgfx::CallbackI::screenShotcallback. If the device is lost before the screenshot is taken,bgfx::CallbackI::fatalreportsFatal::DeviceLostin that frame andscreenShotis not called for this request.
-
void bgfx::touch(ViewId _id)
Submit an empty primitive for rendering. Uniforms and draw state will be applied but no geometry will be submitted.
Remark
These empty draw calls will sort before ordinary draw calls.
- Attention
C99’s equivalent binding is
bgfx_touch.
- Parameters:
_id – [in] View id.
-
void bgfx::discard(uint8_t _flags = BGFX_DISCARD_ALL)
Discard previously set state for draw or compute call.
- Attention
C99’s equivalent binding is
bgfx_discard.
- Parameters:
_flags – [in] Draw/compute states to discard.
Views
Views are the primary sorting mechanism in bgfx. They represent buckets of draw and compute calls, or what are often known as ‘passes’.
When compute calls and draw calls occupy the same bucket, the compute calls will be sorted to execute first.
Compute calls are always executed in order of submission, while draw calls are sorted by internal state if
the View is not in sequential mode.
In most cases where the z-buffer is used, this change in order does not affect the desired output.
When draw call order needs to be preserved (e.g. when rendering GUIs), Views can be set to use sequential mode with bgfx::setViewMode.
Sequential order is less efficient, because it doesn’t allow state change optimization, and should be avoided when possible.
By default, Views are sorted by their View ID, in ascending order.
For dynamic renderers where the right order might not be known until the last moment,
View IDs can be changed to use arbitrary ordering with bgfx::setViewOrder.
A View’s state is preserved between frames.
-
struct ViewMode
View mode sets draw call sort order.
- Attention
C99’s equivalent binding is
bgfx_view_mode_t.
Public Types
-
enum Enum
View modes:
Values:
-
enumerator Default
Default sort order.
-
enumerator Sequential
Sort in the same order in which submit calls were called.
-
enumerator DepthAscending
Sort draw call depth in ascending order.
-
enumerator DepthDescending
Sort draw call depth in descending order.
-
enumerator Count
-
enumerator Default
-
struct ShadingRate
Shading Rate.
- Attention
C99’s equivalent binding is
bgfx_shading_rate_t.
-
void bgfx::setViewName(ViewId _id, const char *_name, int32_t _len = INT32_MAX)
Set view name.
In graphics debugger view name will appear as:
"nnnnc <view name>" ^ ^ ^ | +--- compute (C) +------- view id
Remark
This is debug only feature.
- Attention
C99’s equivalent binding is
bgfx_set_view_name.
- Parameters:
_id – [in] View id.
_name – [in] View name.
_len – [in] View name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.
-
void bgfx::setViewRect(ViewId _id, int16_t _x, int16_t _y, uint16_t _width, uint16_t _height, float _minDepth = 0.0f, float _maxDepth = 1.0f)
Set view rectangle. Draw primitive outside view will be clipped.
- Attention
C99’s equivalent binding is
bgfx_set_view_rect.
- Parameters:
_id – [in] View id.
_x – [in] Position x from the left corner of the window. Can be negative to place view origin outside of the window.
_y – [in] Position y from the top corner of the window. Can be negative to place view origin outside of the window.
_width – [in] Width of view port region.
_height – [in] Height of view port region.
_minDepth – [in] Viewport minimum depth (maps clip-space z=0).
_maxDepth – [in] Viewport maximum depth (maps clip-space z=1).
-
void bgfx::setViewRect(ViewId _id, int16_t _x, int16_t _y, BackbufferRatio::Enum _ratio)
Set view rectangle. Draw primitive outside view will be clipped.
- Attention
C99’s equivalent binding is
bgfx_set_view_rect_ratio.
- Parameters:
_id – [in] View id.
_x – [in] Position x from the left corner of the window. Can be negative to place view origin outside of the window.
_y – [in] Position y from the top corner of the window. Can be negative to place view origin outside of the window.
_ratio – [in] Width and height will be set in respect to back-buffer size. See:
BackbufferRatio::Enum.
-
void bgfx::setViewScissor(ViewId _id, uint16_t _x = 0, uint16_t _y = 0, uint16_t _width = 0, uint16_t _height = 0)
Set view scissor. Draw primitive outside view will be clipped. When _x, _y, _width and _height are set to 0, scissor will be disabled.
- Attention
C99’s equivalent binding is
bgfx_set_view_scissor.
- Parameters:
_id – [in] View id.
_x – [in] Position x from the left corner of the window.
_y – [in] Position y from the top corner of the window.
_width – [in] Width of view scissor region.
_height – [in] Height of view scissor region.
-
void bgfx::setViewDepthBias(ViewId _id, int32_t _constant = 0, float _slopeScale = 0.0f, float _clamp = 0.0f)
Set view depth bias. Applies to all draws in the view unless overridden per-draw with
bgfx::setDepthControl.- Attention
C99’s equivalent binding is
bgfx_set_view_depth_bias.
- Parameters:
_id – [in] View id.
_constant – [in] Constant depth bias.
_slopeScale – [in] Slope-scaled depth bias.
_clamp – [in] Depth bias clamp.
-
void bgfx::setViewSampleMask(ViewId _id, uint32_t _mask = UINT32_MAX)
Set view multisample coverage mask. Combined with the per-draw mask set by
bgfx::setSampleMask, so a draw can narrow the view’s mask but not widen it.- Attention
C99’s equivalent binding is
bgfx_set_view_sample_mask.
- Parameters:
_id – [in] View id.
_mask – [in] Sample coverage mask.
-
void bgfx::setViewClear(ViewId _id, uint16_t _flags, uint32_t _rgba = 0x000000ff, float _depth = 1.0f, uint8_t _stencil = 0)
Set view clear flags.
- Attention
C99’s equivalent binding is
bgfx_set_view_clear.
- Parameters:
_id – [in] View id.
_flags – [in] Clear flags. Use
BGFX_CLEAR_NONEto remove any clear operation. See:BGFX_CLEAR_*._rgba – [in] Color clear value.
_depth – [in] Depth clear value.
_stencil – [in] Stencil clear value.
-
void bgfx::setViewClear(ViewId _id, uint16_t _flags, float _depth, uint8_t _stencil, uint8_t _c0 = UINT8_MAX, uint8_t _c1 = UINT8_MAX, uint8_t _c2 = UINT8_MAX, uint8_t _c3 = UINT8_MAX, uint8_t _c4 = UINT8_MAX, uint8_t _c5 = UINT8_MAX, uint8_t _c6 = UINT8_MAX, uint8_t _c7 = UINT8_MAX)
Set view clear flags with different clear color for each frame buffer texture.
bgfx::setPaletteColormust be used to set up a clear color palette. Frame buffer attachment with palette index set toUINT8_MAXis not cleared.- Attention
C99’s equivalent binding is
bgfx_set_view_clear_mrt.
- Parameters:
_id – [in] View id.
_flags – [in] Clear flags. Use
BGFX_CLEAR_NONEto remove any clear operation. See:BGFX_CLEAR_*._depth – [in] Depth clear value.
_stencil – [in] Stencil clear value.
_c0 – [in] Palette index for frame buffer attachment 0.
_c1 – [in] Palette index for frame buffer attachment 1.
_c2 – [in] Palette index for frame buffer attachment 2.
_c3 – [in] Palette index for frame buffer attachment 3.
_c4 – [in] Palette index for frame buffer attachment 4.
_c5 – [in] Palette index for frame buffer attachment 5.
_c6 – [in] Palette index for frame buffer attachment 6.
_c7 – [in] Palette index for frame buffer attachment 7.
-
void bgfx::setViewMode(ViewId _id, ViewMode::Enum _mode = ViewMode::Default)
Set view sorting mode.
Remark
View mode must be set prior calling
bgfx::submitfor the view.- Attention
C99’s equivalent binding is
bgfx_set_view_mode.
- Parameters:
_id – [in] View id.
_mode – [in] View sort mode. See
ViewMode::Enum.
-
void bgfx::setViewFrameBuffer(ViewId _id, FrameBufferHandle _handle)
Set view frame buffer.
Remark
Not persistent after
bgfx::resetcall.- Attention
C99’s equivalent binding is
bgfx_set_view_frame_buffer.
- Parameters:
_id – [in] View id.
_handle – [in] Frame buffer handle. Passing
BGFX_INVALID_HANDLEas frame buffer handle will draw primitives from this view into default back buffer.
-
void bgfx::setViewTransform(ViewId _id, const void *_view, const void *_proj)
Set view’s view matrix and projection matrix, all draw primitives in this view will use these two matrices.
- Attention
C99’s equivalent binding is
bgfx_set_view_transform.
- Parameters:
_id – [in] View id.
_view – [in] View matrix.
_proj – [in] Projection matrix.
-
void bgfx::setViewOrder(ViewId _id = 0, uint16_t _num = UINT16_MAX, const ViewId *_order = NULL)
Post submit view reordering. A view in
_orderthat currently renders outside the remapped range swaps places with the view it displaces, so the order stays a permutation of all view ids.- Attention
C99’s equivalent binding is
bgfx_set_view_order.
- Parameters:
_id – [in] First view id.
_num – [in] Number of views to remap.
_order – [in] View remap id table. Passing
NULLwill reset view ids to default state.
-
void bgfx::setViewShadingRate(ViewId _id, ShadingRate::Enum _shadingRate = ShadingRate::Rate1x1)
Set view shading rate.
- Attention
Availability depends on:
BGFX_CAPS_VARIABLE_RATE_SHADING.- Attention
C99’s equivalent binding is
bgfx_set_view_shading_rate.
- Parameters:
_id – [in] View id.
_shadingRate – [in] Shading rate.
-
void bgfx::resetView(ViewId _id)
Reset all view settings to default, including the view name.
- Attention
C99’s equivalent binding is
bgfx_reset_view.
- Parameters:
_id – [in] _id View id.
Encoder
Encoder
API for multi-threaded submission.
-
struct Encoder
Encoders are used for submitting draw calls from multiple threads. Only one encoder per thread should be used. Use
bgfx::begin()to obtain an encoder for a thread.- Attention
C99’s equivalent binding is
bgfx_encoder_t.
Public Functions
-
void setMarker(const char *_name, int32_t _len = INT32_MAX)
Sets a debug marker. This allows you to group graphics calls together for easy browsing in graphics debugging tools.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_marker.
- Parameters:
_name – [in] Marker name.
_len – [in] Marker name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.
-
void setState(uint64_t _state, uint32_t _rgba = 0)
Set render states for draw primitive.
Remark
To set up more complex states use:
BGFX_STATE_ALPHA_REF(_ref),BGFX_STATE_POINT_SIZE(_size),BGFX_STATE_BLEND_FUNC(_src, _dst),BGFX_STATE_BLEND_FUNC_SEPARATE(_srcRGB, _dstRGB, _srcA, _dstA),BGFX_STATE_BLEND_EQUATION(_equation),BGFX_STATE_BLEND_EQUATION_SEPARATE(_equationRGB, _equationA)BGFX_STATE_BLEND_EQUATION_ADDis set when no other blend equation is specified.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_state.
- Parameters:
_state – [in] State flags. Default state for primitive type is triangles. See:
BGFX_STATE_DEFAULT.BGFX_STATE_DEPTH_TEST_*- Depth test function.BGFX_STATE_BLEND_*- See remark 1 about BGFX_STATE_BLEND_FUNC.BGFX_STATE_BLEND_EQUATION_*- See remark 2.BGFX_STATE_CULL_*- Backface culling mode.BGFX_STATE_WRITE_*- Enable R, G, B, A or Z write.BGFX_STATE_MSAA- Enable hardware multisample antialiasing.BGFX_STATE_PT_[TRISTRIP/LINES/POINTS]- Primitive type.
_rgba – [in] Sets blend factor used by
BGFX_STATE_BLEND_FACTORandBGFX_STATE_BLEND_INV_FACTORblend modes.
-
void setCondition(OcclusionQueryHandle _handle, bool _visible)
Set condition for rendering.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_condition.
- Parameters:
_handle – [in] Occlusion query handle.
_visible – [in] Render if occlusion query is visible.
-
void setStencil(uint32_t _fstencil, uint32_t _bstencil = BGFX_STENCIL_NONE)
Set stencil test state.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_stencil.
- Parameters:
_fstencil – [in] Front stencil state.
_bstencil – [in] Back stencil state. If back is set to
BGFX_STENCIL_NONE_fstencil is applied to both front and back facing primitives.
-
void setSampleMask(uint32_t _mask = UINT32_MAX)
Set multisample coverage mask for draw primitive. Samples whose bit is clear in the mask are never written, regardless of the coverage the rasterizer computes. Only has an effect when rendering to a multisampled target.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_sample_mask.
- Parameters:
_mask – [in] Sample coverage mask.
-
uint16_t setScissor(uint16_t _x, uint16_t _y, uint16_t _width, uint16_t _height)
Set scissor for draw primitive.
Remark
To scissor for all primitives in view see
bgfx::setViewScissor.- Attention
C99’s equivalent binding is
bgfx_encoder_set_scissor.
- Parameters:
_x – [in] Position x from the left corner of the window.
_y – [in] Position y from the top corner of the window.
_width – [in] Width of view scissor region.
_height – [in] Height of view scissor region.
- Returns:
Scissor cache index.
-
void setScissor(uint16_t _cache = UINT16_MAX)
Set scissor from cache for draw primitive.
Remark
To scissor for all primitives in view see
bgfx::setViewScissor.- Attention
C99’s equivalent binding is
bgfx_encoder_set_scissor_cached.
- Parameters:
_cache – [in] Index in scissor cache.
-
uint16_t setDepthControl(int32_t _constant, float _slopeScale, float _clamp = 0.0f, bool _depthClamp = false)
Set depth control (depth bias and depth clip) for draw primitive. Overrides the view depth bias for this draw.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_depth_control.
- Parameters:
_constant – [in] Constant depth bias.
_slopeScale – [in] Slope-scaled depth bias.
_clamp – [in] Depth bias clamp.
_depthClamp – [in] Disable depth clipping and clamp NDC depth to the [0,1] range instead.
- Returns:
Depth control cache index.
-
void setDepthControl(uint16_t _cache = UINT16_MAX)
Set depth control from depth-control cache for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_depth_control_cached.
- Parameters:
_cache – [in] Index in depth control cache.
-
uint32_t setTransform(const void *_mtx, uint16_t _num = 1)
Set model matrix for draw primitive. If it is not called, the model will be rendered with an identity model matrix.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_transform.
- Parameters:
_mtx – [in] Pointer to first matrix in array.
_num – [in] Number of matrices in array.
- Returns:
Index into matrix cache in case the same model matrix has to be used for other draw primitive call.
-
void setTransform(uint32_t _cache, uint16_t _num = 1)
Set model matrix from matrix cache for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_transform_cached.
- Parameters:
_cache – [in] Index in matrix cache.
_num – [in] Number of matrices from cache.
-
uint32_t allocTransform(Transform *_transform, uint16_t _num)
Reserve matrices in internal matrix cache.
- Attention
Pointer returned can be modified until
bgfx::frameis called.- Attention
C99’s equivalent binding is
bgfx_encoder_alloc_transform.
- Parameters:
_transform – [out] Pointer to
Transformstructure._num – [in] Number of matrices.
- Returns:
Index in matrix cache.
-
void setUniform(UniformHandle _handle, const void *_value, uint16_t _num = 1)
Set shader uniform parameter for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_uniform.
- Parameters:
_handle – [in] Uniform.
_value – [in] Pointer to uniform data.
_num – [in] Number of elements. Passing
UINT16_MAXwill use the _num passed on uniform creation.
-
void setUniformRef(UniformHandle _handle, const void *_value, uint16_t _num = UINT16_MAX)
Set shader uniform parameter by reference. Unlike
Encoder::setUniform, the data is not copied immediately; the renderer reads it from_valueat frame render time. The pointer must remain valid and unchanged until the frame is rendered (up to twobgfx::framecalls with multithreaded submission).- Attention
C99’s equivalent binding is
bgfx_encoder_set_uniform_ref.
- Parameters:
_handle – [in] Uniform.
_value – [in] Pointer to uniform data. Must stay valid until the frame is rendered.
_num – [in] Number of elements. Passing
UINT16_MAXwill use the _num passed on uniform creation.
-
void setIndexBuffer(IndexBufferHandle _handle)
Set index buffer for draw primitive.
- Parameters:
_handle – [in] Index buffer.
-
void setIndexBuffer(IndexBufferHandle _handle, uint32_t _firstIndex, uint32_t _numIndices)
Set index buffer for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_index_buffer.
- Parameters:
_handle – [in] Index buffer.
_firstIndex – [in] First index to render.
_numIndices – [in] Number of indices to render.
-
void setIndexBuffer(DynamicIndexBufferHandle _handle)
Set index buffer for draw primitive.
- Parameters:
_handle – [in] Dynamic index buffer.
-
void setIndexBuffer(DynamicIndexBufferHandle _handle, uint32_t _firstIndex, uint32_t _numIndices)
Set index buffer for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_dynamic_index_buffer.
- Parameters:
_handle – [in] Dynamic index buffer.
_firstIndex – [in] First index to render.
_numIndices – [in] Number of indices to render.
-
void setIndexBuffer(const TransientIndexBuffer *_tib)
Set index buffer for draw primitive.
- Parameters:
_tib – [in] Transient index buffer.
-
void setIndexBuffer(const TransientIndexBuffer *_tib, uint32_t _firstIndex, uint32_t _numIndices)
Set index buffer for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_transient_index_buffer.
- Parameters:
_tib – [in] Transient index buffer.
_firstIndex – [in] First index to render.
_numIndices – [in] Number of indices to render.
-
void setVertexBuffer(uint8_t _stream, VertexBufferHandle _handle)
Set vertex buffer for draw primitive.
- Parameters:
_stream – [in] Vertex stream.
_handle – [in] Vertex buffer.
-
void setVertexBuffer(uint8_t _stream, VertexBufferHandle _handle, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)
Set vertex buffer for draw primitive.
- Attention
C99’s equivalent bindings are
bgfx_encoder_set_vertex_buffer_with_layout,bgfx_encoder_set_vertex_buffer.
- Parameters:
_stream – [in] Vertex stream.
_handle – [in] Vertex buffer.
_startVertex – [in] First vertex to render.
_numVertices – [in] Number of vertices to render.
_layoutHandle – [in] Vertex layout for aliasing vertex buffer. If invalid handle is used, vertex layout used for creation of vertex buffer will be used.
-
void setVertexBuffer(uint8_t _stream, DynamicVertexBufferHandle _handle)
Set vertex buffer for draw primitive.
- Parameters:
_stream – [in] Vertex stream.
_handle – [in] Dynamic vertex buffer.
-
void setVertexBuffer(uint8_t _stream, DynamicVertexBufferHandle _handle, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)
Set vertex buffer for draw primitive.
- Attention
C99’s equivalent bindings are
bgfx_encoder_set_dynamic_vertex_buffer_with_layout,bgfx_encoder_set_dynamic_vertex_buffer.
- Parameters:
_stream – [in] Vertex stream.
_handle – [in] Dynamic vertex buffer.
_startVertex – [in] First vertex to render.
_numVertices – [in] Number of vertices to render.
_layoutHandle – [in] Vertex layout for aliasing vertex buffer. If invalid handle is used, vertex layout used for creation of vertex buffer will be used.
-
void setVertexBuffer(uint8_t _stream, const TransientVertexBuffer *_tvb)
Set vertex buffer for draw primitive.
- Parameters:
_stream – [in] Vertex stream.
_tvb – [in] Transient vertex buffer.
-
void setVertexBuffer(uint8_t _stream, const TransientVertexBuffer *_tvb, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)
Set vertex buffer for draw primitive.
- Attention
C99’s equivalent bindings are
bgfx_encoder_set_transient_vertex_buffer_with_layout,bgfx_encoder_set_transient_vertex_buffer.
- Parameters:
_stream – [in] Vertex stream.
_tvb – [in] Transient vertex buffer.
_startVertex – [in] First vertex to render.
_numVertices – [in] Number of vertices to render.
_layoutHandle – [in] Vertex layout for aliasing vertex buffer. If invalid handle is used, vertex layout used for creation of vertex buffer will be used.
-
void setVertexCount(uint32_t _numVertices)
Set number of vertices for auto generated vertices use in conjunction with gl_VertexID.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_vertex_count.
- Parameters:
_numVertices – [in] Number of vertices.
-
void setInstanceDataBuffer(const InstanceDataBuffer *_idb)
Set instance data buffer for draw primitive.
- Parameters:
_idb – [in] Transient instance data buffer.
-
void setInstanceDataBuffer(const InstanceDataBuffer *_idb, uint32_t _start, uint32_t _num)
Set instance data buffer for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_instance_data_buffer.
- Parameters:
_idb – [in] Transient instance data buffer.
_start – [in] First instance data.
_num – [in] Number of data instances.
-
void setInstanceDataBuffer(VertexBufferHandle _handle, uint32_t _startVertex, uint32_t _num)
Set instance data buffer for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_instance_data_from_vertex_buffer.
- Parameters:
_handle – [in] Vertex buffer.
_startVertex – [in] First instance data.
_num – [in] Number of data instances.
-
void setInstanceDataBuffer(DynamicVertexBufferHandle _handle, uint32_t _startVertex, uint32_t _num)
Set instance data buffer for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_instance_data_from_dynamic_vertex_buffer.
- Parameters:
_handle – [in] Dynamic vertex buffer.
_startVertex – [in] First instance data.
_num – [in] Number of data instances.
-
void setInstanceCount(uint32_t _numInstances)
Set number of instances for auto generated instances use in conjunction with gl_InstanceID.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_instance_count.
- Parameters:
_numInstances – [in] Number of instances.
-
void setTexture(uint8_t _stage, UniformHandle _sampler, TextureHandle _handle, uint32_t _flags = UINT32_MAX)
Set texture stage for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_texture.
- Parameters:
_stage – [in] Texture unit.
_sampler – [in] Program sampler.
_handle – [in] Texture handle.
_flags – [in] Texture sampling mode. Default value UINT32_MAX uses texture sampling settings from the texture.
BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP]- Mirror or clamp to edge wrap mode.BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]- Point or anisotropic sampling.
-
void setTexture(uint8_t _stage, UniformHandle _sampler, TextureHandle _handle, uint16_t _firstLayer, uint16_t _numLayers, uint8_t _firstMip, uint8_t _numMips, uint32_t _flags = UINT32_MAX, uint8_t _lodMin = 0, uint8_t _lodMax = UINT8_MAX)
Set texture stage for draw primitive, selecting a sub-range of the texture’s array layers and mip levels.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_texture_view.
- Parameters:
_stage – [in] Texture unit.
_sampler – [in] Program sampler.
_handle – [in] Texture handle.
_firstLayer – [in] First array layer.
_numLayers – [in] Number of array layers.
_firstMip – [in] First (most detailed) mip level.
_numMips – [in] Number of mip levels.
_flags – [in] Texture sampling mode. Default value UINT32_MAX uses texture sampling settings from the texture.
BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP]- Mirror or clamp to edge wrap mode.BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]- Point or anisotropic sampling.
_lodMin – [in] Lowest (most detailed) level of detail the sampler may use, in quarter-mip steps, relative to
_firstMip._lodMax – [in] Highest (least detailed) level of detail the sampler may use, in quarter-mip steps, relative to
_firstMip.UINT8_MAXleaves it unclamped.
-
void touch(ViewId _id)
Submit an empty primitive for rendering. Uniforms and draw state will be applied but no geometry will be submitted. Useful in cases when no other draw/compute primitive is submitted to view, but it’s desired to execute clear view.
Remark
These empty draw calls will sort before ordinary draw calls.
- Attention
C99’s equivalent binding is
bgfx_encoder_touch.
- Parameters:
_id – [in] View id.
-
void submit(ViewId _id, ProgramHandle _program, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)
Submit primitive for rendering.
- Attention
C99’s equivalent binding is
bgfx_encoder_submit.
- Parameters:
_id – [in] View id.
_program – [in] Program.
_depth – [in] Depth for sorting.
_flags – [in] Discard or preserve states. See
BGFX_DISCARD_*.
-
void submit(ViewId _id, ProgramHandle _program, OcclusionQueryHandle _occlusionQuery, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)
Submit primitive with occlusion query for rendering.
- Attention
C99’s equivalent binding is
bgfx_encoder_submit_occlusion_query.
- Parameters:
_id – [in] View id.
_program – [in] Program.
_occlusionQuery – [in] Occlusion query.
_depth – [in] Depth for sorting.
_flags – [in] Discard or preserve states. See
BGFX_DISCARD_*.
-
void submit(ViewId _id, ProgramHandle _program, IndirectBufferHandle _indirectHandle, uint32_t _start = 0, uint32_t _num = 1, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)
Submit primitive for rendering with index and instance data info from indirect buffer.
- Attention
Availability depends on:
BGFX_CAPS_DRAW_INDIRECT.- Attention
C99’s equivalent binding is
bgfx_encoder_submit_indirect.
- Parameters:
_id – [in] View id.
_program – [in] Program.
_indirectHandle – [in] Indirect buffer.
_start – [in] First element in indirect buffer.
_num – [in] Number of draws.
_depth – [in] Depth for sorting.
_flags – [in] Discard or preserve states. See
BGFX_DISCARD_*.
-
void submit(ViewId _id, ProgramHandle _program, IndirectBufferHandle _indirectHandle, uint32_t _start, IndexBufferHandle _numHandle, uint32_t _numIndex = 0, uint32_t _numMax = UINT32_MAX, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)
Submit primitive for rendering with index and instance data info and draw count from indirect buffers.
- Attention
Availability depends on:
BGFX_CAPS_DRAW_INDIRECT_COUNT.- Attention
C99’s equivalent binding is
bgfx_encoder_submit_indirect_count.
- Parameters:
_id – [in] View id.
_program – [in] Program.
_indirectHandle – [in] Indirect buffer.
_start – [in] First element in indirect buffer.
_numHandle – [in] Buffer for number of draws. Must be created with
BGFX_BUFFER_INDEX32andBGFX_BUFFER_DRAW_INDIRECT._numIndex – [in] Element in number buffer.
_numMax – [in] Max number of draws.
_depth – [in] Depth for sorting.
_flags – [in] Discard or preserve states. See
BGFX_DISCARD_*.
-
void setBuffer(uint8_t _stage, IndexBufferHandle _handle, Access::Enum _access, uint32_t _offset = 0, uint32_t _size = UINT32_MAX)
Set compute index buffer.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_compute_index_buffer.
- Parameters:
_stage – [in] Compute stage.
_handle – [in] Index buffer handle.
_access – [in] Buffer access. See
Access::Enum._offset – [in] Byte offset the shader’s view of the buffer starts at. Must be a multiple of 256 bytes.
_size – [in] Bytes bound from the offset,
UINT32_MAXfor the rest of the buffer.
-
void setBuffer(uint8_t _stage, VertexBufferHandle _handle, Access::Enum _access, uint32_t _offset = 0, uint32_t _size = UINT32_MAX)
Set compute vertex buffer.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_compute_vertex_buffer.
- Parameters:
_stage – [in] Compute stage.
_handle – [in] Vertex buffer handle.
_access – [in] Buffer access. See
Access::Enum._offset – [in] Byte offset the shader’s view of the buffer starts at. Must be a multiple of 256 bytes.
_size – [in] Bytes bound from the offset,
UINT32_MAXfor the rest of the buffer.
-
void setBuffer(uint8_t _stage, DynamicIndexBufferHandle _handle, Access::Enum _access, uint32_t _offset = 0, uint32_t _size = UINT32_MAX)
Set compute dynamic index buffer.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_compute_dynamic_index_buffer.
- Parameters:
_stage – [in] Compute stage.
_handle – [in] Dynamic index buffer handle.
_access – [in] Buffer access. See
Access::Enum._offset – [in] Byte offset the shader’s view of the buffer starts at. Must be a multiple of 256 bytes.
_size – [in] Bytes bound from the offset,
UINT32_MAXfor the rest of the buffer.
-
void setBuffer(uint8_t _stage, DynamicVertexBufferHandle _handle, Access::Enum _access, uint32_t _offset = 0, uint32_t _size = UINT32_MAX)
Set compute dynamic vertex buffer.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_compute_dynamic_vertex_buffer.
- Parameters:
_stage – [in] Compute stage.
_handle – [in] Dynamic vertex buffer handle.
_access – [in] Buffer access. See
Access::Enum._offset – [in] Byte offset the shader’s view of the buffer starts at. Must be a multiple of 256 bytes.
_size – [in] Bytes bound from the offset,
UINT32_MAXfor the rest of the buffer.
-
void setBuffer(uint8_t _stage, IndirectBufferHandle _handle, Access::Enum _access)
Set compute indirect buffer.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_compute_indirect_buffer.
- Parameters:
_stage – [in] Compute stage.
_handle – [in] Indirect buffer handle.
_access – [in] Buffer access. See
Access::Enum.
-
void setImage(uint8_t _stage, TextureHandle _handle, uint8_t _mip, Access::Enum _access, TextureFormat::Enum _format = TextureFormat::Count)
Set compute image from texture.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_image.
- Parameters:
_stage – [in] Compute stage.
_handle – [in] Texture handle.
_mip – [in] Mip level.
_access – [in] Image access. See
Access::Enum._format – [in] Texture format. See:
TextureFormat::Enum.
-
void setImage(uint8_t _stage, TextureHandle _handle, uint16_t _firstLayer, uint16_t _numLayers, uint8_t _mip, Access::Enum _access, TextureFormat::Enum _format = TextureFormat::Count)
Set compute image stage for draw primitive, selecting a sub-range of the texture’s array layers and mip levels.
- Attention
C99’s equivalent binding is
bgfx_encoder_set_image_view.
- Parameters:
_stage – [in] Compute stage.
_handle – [in] Texture handle.
_firstLayer – [in] First array layer.
_numLayers – [in] Number of array layers.
_mip – [in] Mip level.
_access – [in] Image access. See
Access::Enum._format – [in] Texture format. See:
TextureFormat::Enum.
-
void dispatch(ViewId _id, ProgramHandle _program, uint32_t _numX = 1, uint32_t _numY = 1, uint32_t _numZ = 1, uint8_t _flags = BGFX_DISCARD_ALL)
Dispatch compute.
- Attention
C99’s equivalent binding is
bgfx_encoder_dispatch.
- Parameters:
_id – [in] View id.
_program – [in] Compute program.
_numX – [in] Number of groups X.
_numY – [in] Number of groups Y.
_numZ – [in] Number of groups Z.
_flags – [in] Discard or preserve states. See
BGFX_DISCARD_*.
-
void dispatch(ViewId _id, ProgramHandle _program, IndirectBufferHandle _indirectHandle, uint32_t _start = 0, uint32_t _num = 1, uint8_t _flags = BGFX_DISCARD_ALL)
Dispatch compute indirect.
- Attention
C99’s equivalent binding is
bgfx_encoder_dispatch_indirect.
- Parameters:
_id – [in] View id.
_program – [in] Compute program.
_indirectHandle – [in] Indirect buffer.
_start – [in] First element in indirect buffer.
_num – [in] Number of dispatches.
_flags – [in] Discard or preserve states. See
BGFX_DISCARD_*.
-
void discard(uint8_t _flags = BGFX_DISCARD_ALL)
Discard previously set state for draw or compute call.
- Attention
C99’s equivalent binding is
bgfx_encoder_discard.
- Parameters:
_flags – [in] Discard or preserve states. See
BGFX_DISCARD_*.
-
void blit(ViewId _id, const TextureRegion &_dst, const TextureRegion &_src)
Blit texture region between two textures.
Blit is performed on GPU, and it is ordered within the view. In views, all draw commands are executed after blit and compute commands.
Remark
The copy covers the region the two sides have in common: each side gives the origin it starts at, and the size is the smaller of the two extents. A zero
width,heightordepthextends to the rest of that mip.- Attention
Destination texture must be created with
BGFX_TEXTURE_BLIT_DSTflag.- Attention
A depth texture, or one created with
BGFX_TEXTURE_MSAA_SAMPLE, can only be blitted whole: both sides start at the origin of mips of the same size, and the copy covers the whole mip.- Attention
C99’s equivalent binding is
bgfx_encoder_blit.
- Parameters:
_id – [in] View id.
_dst – [in] Destination texture region.
_src – [in] Source texture region.
-
void blit(ViewId _id, const BufferRegion &_dst, const BufferRegion &_src)
Blit buffer region between two buffers.
Buffer blit is performed on GPU, and it is ordered within the view, same as texture blit. In views, all draw commands are executed after blit and compute commands.
Remark
The source region gives the number of bytes copied, and the destination region gives only the offset they land at. A zero
sizecopies the rest of the source buffer.rowPitchandslicePitchare unused.- Attention
Source buffer must be created with one of
BGFX_BUFFER_COMPUTE_*, orBGFX_BUFFER_DRAW_INDIRECTflags.- Attention
Destination buffer must be created with
BGFX_BUFFER_COMPUTE_WRITE, orBGFX_BUFFER_DRAW_INDIRECTflag.- Attention
Source and destination buffer must be different.
- Attention
C99’s equivalent binding is
bgfx_encoder_blit_buffer.
- Parameters:
_id – [in] View id.
_dst – [in] Destination buffer region.
_src – [in] Source buffer region.
-
void blit(ViewId _id, const BufferRegion &_dst, const TextureRegion &_src)
Blit texture region into buffer.
Blit is performed on GPU, and it is ordered within the view, same as texture blit. In views, all draw commands are executed after blit and compute commands.
Remark
The texture region gives the size of the copy.
BufferRegion::rowPitchandslicePitchchoose how the texels are laid out in the buffer, and 0 packs them tightly.BufferRegion::initfills in the layout the backend copies fastest, and bgfx repacks internally for any other layout.- Attention
Destination buffer must be created with
BGFX_BUFFER_COMPUTE_WRITE, orBGFX_BUFFER_DRAW_INDIRECTflag.- Attention
C99’s equivalent binding is
bgfx_encoder_blit_to_buffer.
- Parameters:
_id – [in] View id.
_dst – [in] Destination buffer region.
_src – [in] Source texture region.
-
void blit(ViewId _id, const TextureRegion &_dst, const BufferRegion &_src)
Blit buffer contents into texture region.
Blit is performed on GPU, and it is ordered within the view, same as texture blit. In views, all draw commands are executed after blit and compute commands.
Remark
The texture region gives the size of the copy.
BufferRegion::rowPitchandslicePitchdescribe how the texels are laid out in the buffer, and 0 reads them tightly packed.BufferRegion::initfills in the layout the backend copies fastest, and bgfx repacks internally for any other layout.- Attention
Source buffer must be created with one of
BGFX_BUFFER_COMPUTE_*, orBGFX_BUFFER_DRAW_INDIRECTflags.- Attention
Destination texture must be created with
BGFX_TEXTURE_BLIT_DSTflag.- Attention
C99’s equivalent binding is
bgfx_encoder_blit_from_buffer.
- Parameters:
_id – [in] View id.
_dst – [in] Destination texture region.
_src – [in] Source buffer region.
-
Encoder *bgfx::begin(bool _forceNewEncoder = false)
Begin submitting draw calls from thread. Obtains an encoder that can be used to submit draw calls, compute dispatches, and state changes.
In multithreaded mode (
BGFX_CONFIG_MULTITHREADED=1), multiple threads can each obtain their own encoder and submit draw calls in parallel. Each encoder writes into its own uniform buffer, so there is no contention between threads. The maximum number of simultaneous encoders is configured viaLimits.maxEncodersinbgfx::Init(default: 8).When called from the API thread (the thread that called
bgfx::init) with_forceNewEncoderset tofalse, the default internal encoder (encoder 0) is returned. This is the same encoder used by the legacy non-encoder API (bgfx::setState,bgfx::submit, etc.). When called from a worker thread (or with_forceNewEncoderset totrue), a new encoder is allocated from the encoder pool.Remark
The returned
Encoderpointer is valid untilbgfx::endis called with it. All encoders must be ended beforebgfx::frameis called. Ifbgfx::frameis called while encoders are still active, it will wait for them to finish. ReturnsNULLif no encoder slots are available (allmaxEncodersslots are in use). See also:bgfx::end,bgfx::frame.- Attention
C99’s equivalent binding is
bgfx_encoder_begin.
- Parameters:
_forceNewEncoder – [in] Force allocation of a new encoder from the pool, even when called from the API thread.
- Returns:
-
void bgfx::end(Encoder *_encoder)
End submitting draw calls from thread. Returns the encoder obtained from
bgfx::beginback to the encoder pool.After this call the
Encoderpointer is no longer valid and must not be used. The encoder’s recorded draw calls and state changes are finalized and will be included in the next frame whenbgfx::frameis called.Remark
Must be called from the same thread that called
bgfx::beginfor this encoder. All encoders must be ended beforebgfx::frameis called. The default encoder (encoder 0, used by the legacy API) is managed internally and does not need to be passed tobgfx::end; passing it is harmless but has no effect. See also:bgfx::begin,bgfx::frame.- Attention
C99’s equivalent binding is
bgfx_encoder_end.
- Parameters:
_encoder – [in] Encoder.
Draw
Draw state is not preserved between two draw calls.
All state is cleared after calling bgfx::submit.
Debug
Debug markers for grouping draw calls in graphics debugging tools.
-
void bgfx::setName(ShaderHandle _handle, const char *_name, int32_t _len = INT32_MAX)
Set shader debug name.
- Attention
C99’s equivalent binding is
bgfx_set_shader_name.
- Parameters:
_handle – [in] Shader handle.
_name – [in] Shader name.
_len – [in] Shader name length (if length is INT32_MAX, it’s expected that _name is zero terminated string).
-
void bgfx::setName(TextureHandle _handle, const char *_name, int32_t _len = INT32_MAX)
Set texture debug name.
- Attention
C99’s equivalent binding is
bgfx_set_texture_name.
- Parameters:
_handle – [in] Texture handle.
_name – [in] Texture name.
_len – [in] Texture name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.
-
void bgfx::setMarker(const char *_name, int32_t _len = INT32_MAX)
Sets a debug marker. This allows you to group graphics calls together for easy browsing in graphics debugging tools.
- Attention
C99’s equivalent binding is
bgfx_set_marker.
- Parameters:
_name – [in] Marker name.
_len – [in] Marker name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.
State
Configure render state for draw calls.
-
void bgfx::setState(uint64_t _state, uint32_t _rgba = 0)
Set render states for draw primitive.
Remark
To set up more complex states use:
BGFX_STATE_ALPHA_REF(_ref),BGFX_STATE_POINT_SIZE(_size),BGFX_STATE_BLEND_FUNC(_src, _dst),BGFX_STATE_BLEND_FUNC_SEPARATE(_srcRGB, _dstRGB, _srcA, _dstA),BGFX_STATE_BLEND_EQUATION(_equation),BGFX_STATE_BLEND_EQUATION_SEPARATE(_equationRGB, _equationA)BGFX_STATE_BLEND_EQUATION_ADDis set when no other blend equation is specified.
- Attention
C99’s equivalent binding is
bgfx_set_state.
- Parameters:
_state – [in] State flags. Default state for primitive type is triangles. See:
BGFX_STATE_DEFAULT.BGFX_STATE_DEPTH_TEST_*- Depth test function.BGFX_STATE_BLEND_*- See remark 1 about BGFX_STATE_BLEND_FUNC.BGFX_STATE_BLEND_EQUATION_*- See remark 2.BGFX_STATE_CULL_*- Backface culling mode.BGFX_STATE_WRITE_*- Enable R, G, B, A or Z write.BGFX_STATE_MSAA- Enable hardware multisample antialiasing.BGFX_STATE_PT_[TRISTRIP/LINES/POINTS]- Primitive type.
_rgba – [in] Sets blend factor used by
BGFX_STATE_BLEND_FACTORandBGFX_STATE_BLEND_INV_FACTORblend modes.
-
void bgfx::setSampleMask(uint32_t _mask = UINT32_MAX)
Set multisample coverage mask for draw primitive. Samples whose bit is clear in the mask are never written, regardless of the coverage the rasterizer computes. Only has an effect when rendering to a multisampled target.
- Attention
C99’s equivalent binding is
bgfx_set_sample_mask.
- Parameters:
_mask – [in] Sample coverage mask.
-
uint16_t bgfx::setDepthControl(int32_t _constant, float _slopeScale, float _clamp = 0.0f, bool _depthClamp = false)
Set depth control (depth bias and depth clip) for draw primitive. Overrides the view depth bias for this draw.
- Attention
C99’s equivalent binding is
bgfx_set_depth_control.
- Parameters:
_constant – [in] Constant depth bias.
_slopeScale – [in] Slope-scaled depth bias.
_clamp – [in] Depth bias clamp.
_depthClamp – [in] Disable depth clipping and clamp NDC depth to the [0,1] range instead.
- Returns:
Depth control cache index.
-
void bgfx::setDepthControl(uint16_t _cache = UINT16_MAX)
Set depth control from depth-control cache for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_set_depth_control_cached.
- Parameters:
_cache – [in] Index in depth control cache.
State Flags
Render state flags for depth test, blending, culling, etc.
Write
-
BGFX_STATE_WRITE_R
Enable R write.
Color RGB/alpha/depth write. When it’s not specified write will be disabled.
-
BGFX_STATE_WRITE_G
Enable G write.
-
BGFX_STATE_WRITE_B
Enable B write.
-
BGFX_STATE_WRITE_A
Enable alpha write.
-
BGFX_STATE_WRITE_Z
Enable depth write. Enable RGB write.
-
BGFX_STATE_WRITE_RGB
-
BGFX_STATE_WRITE_MASK
Write all channels mask.
Depth Test
-
BGFX_STATE_DEPTH_TEST_LESS
Enable depth test, less.
Depth test state. When
BGFX_STATE_DEPTH_is not specified depth test will be disabled.
-
BGFX_STATE_DEPTH_TEST_LEQUAL
Enable depth test, less or equal.
-
BGFX_STATE_DEPTH_TEST_EQUAL
Enable depth test, equal.
-
BGFX_STATE_DEPTH_TEST_GEQUAL
Enable depth test, greater or equal.
-
BGFX_STATE_DEPTH_TEST_GREATER
Enable depth test, greater.
-
BGFX_STATE_DEPTH_TEST_NOTEQUAL
Enable depth test, not equal.
-
BGFX_STATE_DEPTH_TEST_NEVER
Enable depth test, never.
-
BGFX_STATE_DEPTH_TEST_ALWAYS
Enable depth test, always.
Blend Mode
-
BGFX_STATE_BLEND_ZERO
0, 0, 0, 0
Use BGFX_STATE_BLEND_FUNC(_src, _dst) or BGFX_STATE_BLEND_FUNC_SEPARATE(_srcRGB, _dstRGB, _srcA, _dstA) helper macros.
-
BGFX_STATE_BLEND_ONE
1, 1, 1, 1
-
BGFX_STATE_BLEND_SRC_COLOR
Rs, Gs, Bs, As.
-
BGFX_STATE_BLEND_INV_SRC_COLOR
1-Rs, 1-Gs, 1-Bs, 1-As
-
BGFX_STATE_BLEND_SRC_ALPHA
As, As, As, As.
-
BGFX_STATE_BLEND_INV_SRC_ALPHA
1-As, 1-As, 1-As, 1-As
-
BGFX_STATE_BLEND_DST_ALPHA
Ad, Ad, Ad, Ad.
-
BGFX_STATE_BLEND_INV_DST_ALPHA
1-Ad, 1-Ad, 1-Ad ,1-Ad
-
BGFX_STATE_BLEND_DST_COLOR
Rd, Gd, Bd, Ad.
-
BGFX_STATE_BLEND_INV_DST_COLOR
1-Rd, 1-Gd, 1-Bd, 1-Ad
-
BGFX_STATE_BLEND_SRC_ALPHA_SAT
f, f, f, 1; f = min(As, 1-Ad)
-
BGFX_STATE_BLEND_FACTOR
Blend factor.
-
BGFX_STATE_BLEND_INV_FACTOR
1-Blend factor
Blend Equation
-
BGFX_STATE_BLEND_EQUATION_ADD
Blend add: src + dst.
Use BGFX_STATE_BLEND_EQUATION(_equation) or BGFX_STATE_BLEND_EQUATION_SEPARATE(_equationRGB, _equationA) helper macros.
-
BGFX_STATE_BLEND_EQUATION_SUB
Blend subtract: src - dst.
-
BGFX_STATE_BLEND_EQUATION_REVSUB
Blend reverse subtract: dst - src.
-
BGFX_STATE_BLEND_EQUATION_MIN
Blend min: min(src, dst).
-
BGFX_STATE_BLEND_EQUATION_MAX
Blend max: max(src, dst).
Primitive Culling
-
BGFX_STATE_CULL_CW
Cull clockwise triangles.
Cull state. When
BGFX_STATE_CULL_*is not specified culling will be disabled.
-
BGFX_STATE_CULL_CCW
Cull counter-clockwise triangles.
Primitive Type
-
BGFX_STATE_PT_TRISTRIP
Tristrip.
-
BGFX_STATE_PT_LINES
Lines.
-
BGFX_STATE_PT_LINESTRIP
Line strip.
-
BGFX_STATE_PT_POINTS
Points.
Misc
-
BGFX_STATE_MSAA
Enable MSAA rasterization.
Enable MSAA write when writing into MSAA frame buffer. This flag is ignored when not writing into MSAA frame buffer.
-
BGFX_STATE_LINEAA
Enable line AA rasterization.
-
BGFX_STATE_CONSERVATIVE_RASTER
Enable conservative rasterization.
-
BGFX_STATE_NONE
No state.
-
BGFX_STATE_FRONT_CCW
Front counter-clockwise (default is clockwise).
-
BGFX_STATE_BLEND_INDEPENDENT
Enable blend independent.
-
BGFX_STATE_BLEND_ALPHA_TO_COVERAGE
Enable alpha to coverage. Default state is write to RGB, alpha, and depth with depth test less enabled, with clockwise culling and MSAA (when writing into MSAA frame buffer, otherwise this flag is ignored).
-
BGFX_STATE_DEFAULT
Stencil
Configure stencil test for draw calls.
-
void bgfx::setStencil(uint32_t _fstencil, uint32_t _bstencil = BGFX_STENCIL_NONE)
Set stencil test state.
- Attention
C99’s equivalent binding is
bgfx_set_stencil.
- Parameters:
_fstencil – [in] Front stencil state.
_bstencil – [in] Back stencil state. If back is set to
BGFX_STENCIL_NONE_fstencil is applied to both front and back facing primitives.
Stencil Flags
Stencil test configuration flags.
-
BGFX_STENCIL_TEST_LESS
Enable stencil test, less.
-
BGFX_STENCIL_TEST_LEQUAL
Enable stencil test, less or equal.
-
BGFX_STENCIL_TEST_EQUAL
Enable stencil test, equal.
-
BGFX_STENCIL_TEST_GEQUAL
Enable stencil test, greater or equal.
-
BGFX_STENCIL_TEST_GREATER
Enable stencil test, greater.
-
BGFX_STENCIL_TEST_NOTEQUAL
Enable stencil test, not equal.
-
BGFX_STENCIL_TEST_NEVER
Enable stencil test, never.
-
BGFX_STENCIL_TEST_ALWAYS
Enable stencil test, always.
Scissor
If the Scissor rectangle needs to be changed for
every draw call in a View, use bgfx::setScissor.
Otherwise, use bgfx::setViewScissor.
-
uint16_t bgfx::setScissor(uint16_t _x, uint16_t _y, uint16_t _width, uint16_t _height)
Set scissor for draw primitive.
Remark
To scissor for all primitives in view see
bgfx::setViewScissor.- Attention
C99’s equivalent binding is
bgfx_set_scissor.
- Parameters:
_x – [in] Position x from the left corner of the window.
_y – [in] Position y from the top corner of the window.
_width – [in] Width of view scissor region.
_height – [in] Height of view scissor region.
- Returns:
Scissor cache index.
-
void bgfx::setScissor(uint16_t _cache = UINT16_MAX)
Set scissor from cache for draw primitive.
Remark
To scissor for all primitives in view see
bgfx::setViewScissor.- Attention
C99’s equivalent binding is
bgfx_set_scissor_cached.
- Parameters:
_cache – [in] Index in scissor cache.
Transform
Set model transform matrices for draw calls.
-
uint32_t bgfx::setTransform(const void *_mtx, uint16_t _num = 1)
Set model matrix for draw primitive. If it is not called, the model will be rendered with an identity model matrix.
- Attention
C99’s equivalent binding is
bgfx_set_transform.
- Parameters:
_mtx – [in] Pointer to first matrix in array.
_num – [in] Number of matrices in array.
- Returns:
Index into matrix cache in case the same model matrix has to be used for other draw primitive call.
-
void bgfx::setTransform(uint32_t _cache, uint16_t _num = 1)
Set model matrix from matrix cache for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_set_transform_cached.
- Parameters:
_cache – [in] Index in matrix cache.
_num – [in] Number of matrices from cache.
-
uint32_t bgfx::allocTransform(Transform *_transform, uint16_t _num)
Reserve matrices in internal matrix cache.
- Attention
Pointer returned can be modified until
bgfx::frameis called.- Attention
C99’s equivalent binding is
bgfx_alloc_transform.
- Parameters:
_transform – [out] Pointer to
Transformstructure._num – [in] Number of matrices.
- Returns:
Index in matrix cache.
Conditional Rendering
Conditionally render based on occlusion query results.
-
void bgfx::setCondition(OcclusionQueryHandle _handle, bool _visible)
Set condition for rendering.
- Attention
C99’s equivalent binding is
bgfx_set_condition.
- Parameters:
_handle – [in] Occlusion query handle.
_visible – [in] Render if occlusion query is visible.
Buffers
Set vertex, index, and instance data buffers for draw calls.
-
struct TransientIndexBuffer
Transient index buffer.
- Attention
C99’s equivalent binding is
bgfx_transient_index_buffer_t.
-
struct TransientVertexBuffer
Transient vertex buffer.
- Attention
C99’s equivalent binding is
bgfx_transient_vertex_buffer_t.
-
struct InstanceDataBuffer
Instance data buffer info.
- Attention
C99’s equivalent binding is
bgfx_instance_data_buffer_t.
-
struct BufferRegion
Region of a buffer, used as the source or destination of a blit, or as the region handed to
bgfx::read.rowPitchandslicePitchdescribe how texture data is laid out in the buffer, and are ignored when the other end of the blit is also a buffer. Both are in bytes, and 0 selects the tightly packed layout: a row pitch of the region width in blocks multiplied by the block size, and a slice pitch of that row pitch multiplied by the region height in blocks.A pitch the backend cannot copy natively is repacked by bgfx, which costs an extra pass over the data.
Caps::Limits::blitRowPitchAlignandblitOffsetAlignreport what the backend copies directly, andBufferRegion::initfills in a layout that matches them.- Attention
C99’s equivalent binding is
bgfx_buffer_region_t.
Public Functions
-
void init(const TextureRegion &_texture)
Fill
rowPitch,slicePitchandsizewith the layout the backend copies fastest for_texture, and roundoffsetup toCaps::Limits::blitOffsetAlign.handleis left untouched, sosizecan be used to create the buffer the region will point at.- Attention
C99’s equivalent binding is
bgfx_buffer_region_init_texture.
- Parameters:
_texture – [in] Texture region the buffer is copied to or from.
-
void init(BufferHandle _handle, uint32_t _offset = 0, uint32_t _size = 0)
Fill in the region a blit between two buffers copies.
rowPitchandslicePitchare left at zero, since neither end of such a blit is a texture.- Attention
C99’s equivalent binding is
bgfx_buffer_region_init_buffer.
- Parameters:
_handle – [in] Buffer handle.
_offset – [in] Byte offset into the buffer.
_size – [in] Number of bytes. 0 uses the rest of the buffer.
Public Members
-
BufferHandle handle = {}
Buffer handle.
-
uint32_t offset = 0
Byte offset into the buffer.
-
uint32_t size = 0
Number of bytes. Only used when both ends of a blit are buffers, or by
bgfx::read. 0 uses the rest of the buffer.
-
uint32_t rowPitch = 0
Distance in bytes between the start of two consecutive rows of blocks. 0 is tightly packed.
-
uint32_t slicePitch = 0
Distance in bytes between the start of two consecutive slices, layers or cube faces. 0 is tightly packed.
-
void bgfx::setIndexBuffer(IndexBufferHandle _handle)
Set index buffer for draw primitive.
- Parameters:
_handle – [in] Index buffer.
-
void bgfx::setIndexBuffer(IndexBufferHandle _handle, uint32_t _firstIndex, uint32_t _numIndices)
Set index buffer for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_set_index_buffer.
- Parameters:
_handle – [in] Index buffer.
_firstIndex – [in] First index to render.
_numIndices – [in] Number of indices to render.
-
void bgfx::setIndexBuffer(DynamicIndexBufferHandle _handle)
Set index buffer for draw primitive.
- Parameters:
_handle – [in] Dynamic index buffer.
-
void bgfx::setIndexBuffer(DynamicIndexBufferHandle _handle, uint32_t _firstIndex, uint32_t _numIndices)
Set index buffer for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_set_dynamic_index_buffer.
- Parameters:
_handle – [in] Dynamic index buffer.
_firstIndex – [in] First index to render.
_numIndices – [in] Number of indices to render.
-
void bgfx::setIndexBuffer(const TransientIndexBuffer *_tib)
Set index buffer for draw primitive.
- Parameters:
_tib – [in] Transient index buffer.
-
void bgfx::setIndexBuffer(const TransientIndexBuffer *_tib, uint32_t _firstIndex, uint32_t _numIndices)
Set index buffer for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_set_transient_index_buffer.
- Parameters:
_tib – [in] Transient index buffer.
_firstIndex – [in] First index to render.
_numIndices – [in] Number of indices to render.
-
void bgfx::setVertexBuffer(uint8_t _stream, VertexBufferHandle _handle, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)
Set vertex buffer for draw primitive.
- Attention
C99’s equivalent bindings are
bgfx_set_vertex_buffer_with_layout,bgfx_set_vertex_buffer.
- Parameters:
_stream – [in] Vertex stream.
_handle – [in] Vertex buffer.
_startVertex – [in] First vertex to render.
_numVertices – [in] Number of vertices to render.
_layoutHandle – [in] Vertex layout for aliasing vertex buffer. If invalid handle is used, vertex layout used for creation of vertex buffer will be used.
-
void bgfx::setVertexBuffer(uint8_t _stream, DynamicVertexBufferHandle _handle, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)
Set vertex buffer for draw primitive.
- Attention
C99’s equivalent bindings are
bgfx_set_dynamic_vertex_buffer_with_layout,bgfx_set_dynamic_vertex_buffer.
- Parameters:
_stream – [in] Vertex stream.
_handle – [in] Dynamic vertex buffer.
_startVertex – [in] First vertex to render.
_numVertices – [in] Number of vertices to render.
_layoutHandle – [in] Vertex layout for aliasing vertex buffer. If invalid handle is used, vertex layout used for creation of vertex buffer will be used.
-
void bgfx::setVertexBuffer(uint8_t _stream, const TransientVertexBuffer *_tvb, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)
Set vertex buffer for draw primitive.
- Attention
C99’s equivalent bindings are
bgfx_set_transient_vertex_buffer_with_layout,bgfx_set_transient_vertex_buffer.
- Parameters:
_stream – [in] Vertex stream.
_tvb – [in] Transient vertex buffer.
_startVertex – [in] First vertex to render.
_numVertices – [in] Number of vertices to render.
_layoutHandle – [in] Vertex layout for aliasing vertex buffer. If invalid handle is used, vertex layout used for creation of vertex buffer will be used.
-
void bgfx::setVertexCount(uint32_t _numVertices)
Set number of vertices for auto generated vertices use in conjunction with gl_VertexID.
- Attention
C99’s equivalent binding is
bgfx_set_vertex_count.
- Parameters:
_numVertices – [in] Number of vertices.
-
void bgfx::setInstanceDataBuffer(const InstanceDataBuffer *_idb)
Set instance data buffer for draw primitive.
- Parameters:
_idb – [in] Transient instance data buffer.
-
void bgfx::setInstanceDataBuffer(const InstanceDataBuffer *_idb, uint32_t _start, uint32_t _num)
Set instance data buffer for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_set_instance_data_buffer.
- Parameters:
_idb – [in] Transient instance data buffer.
_start – [in] First instance data.
_num – [in] Number of data instances.
-
void bgfx::setInstanceDataBuffer(VertexBufferHandle _handle, uint32_t _startVertex, uint32_t _num)
Set instance data buffer for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_set_instance_data_from_vertex_buffer.
- Parameters:
_handle – [in] Vertex buffer.
_startVertex – [in] First instance data.
_num – [in] Number of data instances.
-
void bgfx::setInstanceDataBuffer(DynamicVertexBufferHandle _handle, uint32_t _startVertex, uint32_t _num)
Set instance data buffer for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_set_instance_data_from_dynamic_vertex_buffer.
- Parameters:
_handle – [in] Dynamic vertex buffer.
_startVertex – [in] First instance data.
_num – [in] Number of data instances.
-
void bgfx::setInstanceCount(uint32_t _numInstances)
Set number of instances for auto generated instances use in conjunction with gl_InstanceID.
- Attention
C99’s equivalent binding is
bgfx_set_instance_count.
- Parameters:
_numInstances – [in] Number of instances.
Textures
Bind textures to texture stages for draw calls.
-
void bgfx::setTexture(uint8_t _stage, UniformHandle _sampler, TextureHandle _handle, uint32_t _flags = UINT32_MAX)
Set texture stage for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_set_texture.
- Parameters:
_stage – [in] Texture unit.
_sampler – [in] Program sampler.
_handle – [in] Texture handle.
_flags – [in] Texture sampling mode. Default value UINT32_MAX uses texture sampling settings from the texture.
BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP]- Mirror or clamp to edge wrap mode.BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]- Point or anisotropic sampling.
-
void bgfx::setTexture(uint8_t _stage, UniformHandle _sampler, TextureHandle _handle, uint16_t _firstLayer, uint16_t _numLayers, uint8_t _firstMip, uint8_t _numMips, uint32_t _flags = UINT32_MAX, uint8_t _lodMin = 0, uint8_t _lodMax = UINT8_MAX)
Set texture stage for draw primitive, selecting a sub-range of the texture’s array layers and mip levels.
- Attention
C99’s equivalent binding is
bgfx_set_texture_view.
- Parameters:
_stage – [in] Texture unit.
_sampler – [in] Program sampler.
_handle – [in] Texture handle.
_firstLayer – [in] First array layer.
_numLayers – [in] Number of array layers.
_firstMip – [in] First (most detailed) mip level.
_numMips – [in] Number of mip levels.
_flags – [in] Texture sampling mode. Default value UINT32_MAX uses texture sampling settings from the texture.
BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP]- Mirror or clamp to edge wrap mode.BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]- Point or anisotropic sampling.
_lodMin – [in] Lowest (most detailed) level of detail the sampler may use, in quarter-mip steps, relative to
_firstMip._lodMax – [in] Highest (least detailed) level of detail the sampler may use, in quarter-mip steps, relative to
_firstMip.UINT8_MAXleaves it unclamped.
Uniforms
Set shader uniform parameters for draw calls.
-
void bgfx::setViewUniform(ViewId _id, UniformHandle _handle, const void *_value, uint16_t _num = 1)
Set shader uniform parameter for view.
- Attention
Uniform must be created with
bgfx::UniformFreq::Viewargument.- Attention
C99’s equivalent binding is
bgfx_set_view_uniform.
- Parameters:
_id – [in] View id.
_handle – [in] Uniform.
_value – [in] Pointer to uniform data.
_num – [in] Number of elements. Passing
UINT16_MAXwill use the _num passed on uniform creation.
-
void bgfx::setFrameUniform(UniformHandle _handle, const void *_value, uint16_t _num = 1)
Set shader uniform parameter for frame.
- Attention
Uniform must be created with
bgfx::UniformFreq::Frameargument.- Attention
C99’s equivalent binding is
bgfx_set_frame_uniform.
- Parameters:
_handle – [in] Uniform.
_value – [in] Pointer to uniform data.
_num – [in] Number of elements. Passing
UINT16_MAXwill use the _num passed on uniform creation.
-
void bgfx::setUniform(UniformHandle _handle, const void *_value, uint16_t _num = 1)
Set shader uniform parameter for draw primitive.
- Attention
C99’s equivalent binding is
bgfx_set_uniform.
- Parameters:
_handle – [in] Uniform.
_value – [in] Pointer to uniform data.
_num – [in] Number of elements. Passing
UINT16_MAXwill use the _num passed on uniform creation.
-
void bgfx::setUniformRef(UniformHandle _handle, const void *_value, uint16_t _num = UINT16_MAX)
Set shader uniform parameter by reference. Unlike
bgfx::setUniform, the data is not copied immediately; the renderer reads it from_valueat frame render time. The pointer must remain valid and unchanged until the frame is rendered (up to twobgfx::framecalls with multithreaded submission).- Attention
C99’s equivalent binding is
bgfx_set_uniform_ref.
- Parameters:
_handle – [in] Uniform.
_value – [in] Pointer to uniform data. Must stay valid until the frame is rendered.
_num – [in] Number of elements. Passing
UINT16_MAXwill use the _num passed on uniform creation.
Submit
In Views, all draw commands are executed after blit and compute commands.
-
void bgfx::submit(ViewId _id, ProgramHandle _program, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)
Submit primitive for rendering.
- Attention
C99’s equivalent binding is
bgfx_submit.
- Parameters:
_id – [in] View id.
_program – [in] Program.
_depth – [in] Depth for sorting.
_flags – [in] Which states to discard for next draw. See
BGFX_DISCARD_*.
-
void bgfx::submit(ViewId _id, ProgramHandle _program, OcclusionQueryHandle _occlusionQuery, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)
Submit primitive with occlusion query for rendering.
- Attention
C99’s equivalent binding is
bgfx_submit_occlusion_query.
- Parameters:
_id – [in] View id.
_program – [in] Program.
_occlusionQuery – [in] Occlusion query.
_depth – [in] Depth for sorting.
_flags – [in] Which states to discard for next draw. See
BGFX_DISCARD_*.
-
void bgfx::submit(ViewId _id, ProgramHandle _program, IndirectBufferHandle _indirectHandle, uint32_t _start = 0, uint32_t _num = 1, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)
Submit primitive for rendering with index and instance data info from indirect buffer.
- Attention
Availability depends on:
BGFX_CAPS_DRAW_INDIRECT.- Attention
C99’s equivalent binding is
bgfx_submit_indirect.
- Parameters:
_id – [in] View id.
_program – [in] Program.
_indirectHandle – [in] Indirect buffer.
_start – [in] First element in indirect buffer.
_num – [in] Number of draws.
_depth – [in] Depth for sorting.
_flags – [in] Which states to discard for next draw. See
BGFX_DISCARD_*.
-
void bgfx::submit(ViewId _id, ProgramHandle _program, IndirectBufferHandle _indirectHandle, uint32_t _start, IndexBufferHandle _numHandle, uint32_t _numIndex = 0, uint32_t _numMax = UINT32_MAX, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)
Submit primitive for rendering with index and instance data info and draw count from indirect buffers.
- Attention
Availability depends on:
BGFX_CAPS_DRAW_INDIRECT_COUNT.- Attention
C99’s equivalent binding is
bgfx_submit_indirect_count.
- Parameters:
_id – [in] View id.
_program – [in] Program.
_indirectHandle – [in] Indirect buffer.
_start – [in] First element in indirect buffer.
_numHandle – [in] Buffer for number of draws. Must be created with
BGFX_BUFFER_INDEX32andBGFX_BUFFER_DRAW_INDIRECT._numIndex – [in] Element in number buffer.
_numMax – [in] Max number of draws.
_depth – [in] Depth for sorting.
_flags – [in] Which states to discard for next draw. See
BGFX_DISCARD_*.
Compute
Compute state is not preserved between compute dispatches; all state is cleared after calling bgfx::dispatch.
gl_NumWorkGroups can be used in compute shaders, but it’s not supported with indirect dispatch.
Buffers
Bind buffers to compute stages.
-
uint32_t bgfx::read(const BufferRegion &_src, void *_data)
Read back contents of buffer.
Read back is intended for reading GPU written (compute, or draw indirect) buffers back to the CPU. It’s not intended to be used in the main render loop, since it stalls the GPU.
Remark
Read back is asynchronous, and the result is available at the returned frame. A zero
sizereads the rest of the buffer.rowPitchandslicePitchare unused.- Attention
Buffer must be created with one of
BGFX_BUFFER_COMPUTE_*, orBGFX_BUFFER_DRAW_INDIRECTflags.- Attention
C99’s equivalent binding is
bgfx_read_buffer.
- Parameters:
_src – [in] Source buffer region.
_data – [in] Destination buffer.
- Returns:
Frame number when the result will be available. See:
bgfx::frame. If the device is lost before then,bgfx::CallbackI::fatalreportsFatal::DeviceLostin that frame, and_datais left untouched.
-
void bgfx::setBuffer(uint8_t _stage, IndexBufferHandle _handle, Access::Enum _access, uint32_t _offset = 0, uint32_t _size = UINT32_MAX)
Set compute index buffer.
- Attention
C99’s equivalent binding is
bgfx_set_compute_index_buffer.
- Parameters:
_stage – [in] Compute stage.
_handle – [in] Index buffer handle.
_access – [in] Buffer access. See
Access::Enum._offset – [in] Byte offset the shader’s view of the buffer starts at. Must be a multiple of 256 bytes.
_size – [in] Bytes bound from the offset,
UINT32_MAXfor the rest of the buffer.
-
void bgfx::setBuffer(uint8_t _stage, VertexBufferHandle _handle, Access::Enum _access, uint32_t _offset = 0, uint32_t _size = UINT32_MAX)
Set compute vertex buffer.
- Attention
C99’s equivalent binding is
bgfx_set_compute_vertex_buffer.
- Parameters:
_stage – [in] Compute stage.
_handle – [in] Vertex buffer handle.
_access – [in] Buffer access. See
Access::Enum._offset – [in] Byte offset the shader’s view of the buffer starts at. Must be a multiple of 256 bytes.
_size – [in] Bytes bound from the offset,
UINT32_MAXfor the rest of the buffer.
-
void bgfx::setBuffer(uint8_t _stage, DynamicIndexBufferHandle _handle, Access::Enum _access, uint32_t _offset = 0, uint32_t _size = UINT32_MAX)
Set compute dynamic index buffer.
- Attention
C99’s equivalent binding is
bgfx_set_compute_dynamic_index_buffer.
- Parameters:
_stage – [in] Compute stage.
_handle – [in] Dynamic index buffer handle.
_access – [in] Buffer access. See
Access::Enum._offset – [in] Byte offset the shader’s view of the buffer starts at. Must be a multiple of 256 bytes.
_size – [in] Bytes bound from the offset,
UINT32_MAXfor the rest of the buffer.
-
void bgfx::setBuffer(uint8_t _stage, DynamicVertexBufferHandle _handle, Access::Enum _access, uint32_t _offset = 0, uint32_t _size = UINT32_MAX)
Set compute dynamic vertex buffer.
- Attention
C99’s equivalent binding is
bgfx_set_compute_dynamic_vertex_buffer.
- Parameters:
_stage – [in] Compute stage.
_handle – [in] Dynamic vertex buffer handle.
_access – [in] Buffer access. See
Access::Enum._offset – [in] Byte offset the shader’s view of the buffer starts at. Must be a multiple of 256 bytes.
_size – [in] Bytes bound from the offset,
UINT32_MAXfor the rest of the buffer.
-
void bgfx::setBuffer(uint8_t _stage, IndirectBufferHandle _handle, Access::Enum _access)
Set compute indirect buffer.
- Attention
C99’s equivalent binding is
bgfx_set_compute_indirect_buffer.
- Parameters:
_stage – [in] Compute stage.
_handle – [in] Indirect buffer handle.
_access – [in] Buffer access. See
Access::Enum.
Images
Bind texture images to compute stages.
-
void bgfx::setImage(uint8_t _stage, TextureHandle _handle, uint8_t _mip, Access::Enum _access, TextureFormat::Enum _format = TextureFormat::Count)
Set compute image from texture.
- Attention
C99’s equivalent binding is
bgfx_set_image.
- Parameters:
_stage – [in] Compute stage.
_handle – [in] Texture handle.
_mip – [in] Mip level.
_access – [in] Image access. See
Access::Enum._format – [in] Texture format. See:
TextureFormat::Enum.
-
void bgfx::setImage(uint8_t _stage, TextureHandle _handle, uint16_t _firstLayer, uint16_t _numLayers, uint8_t _mip, Access::Enum _access, TextureFormat::Enum _format = TextureFormat::Count)
Set compute image stage for draw primitive, selecting a sub-range of the texture’s array layers and mip levels.
- Attention
C99’s equivalent binding is
bgfx_set_image_view.
- Parameters:
_stage – [in] Compute stage.
_handle – [in] Texture handle.
_firstLayer – [in] First array layer.
_numLayers – [in] Number of array layers.
_mip – [in] Mip level.
_access – [in] Image access. See
Access::Enum._format – [in] Texture format. See:
TextureFormat::Enum.
Dispatch
In Views, all draw commands are executed after blit and compute commands.
-
void bgfx::dispatch(ViewId _id, ProgramHandle _program, uint32_t _numX = 1, uint32_t _numY = 1, uint32_t _numZ = 1, uint8_t _flags = BGFX_DISCARD_ALL)
Dispatch compute.
- Attention
C99’s equivalent binding is
bgfx_dispatch.
- Parameters:
_id – [in] View id.
_program – [in] Compute program.
_numX – [in] Number of groups X.
_numY – [in] Number of groups Y.
_numZ – [in] Number of groups Z.
_flags – [in] Discard or preserve states. See
BGFX_DISCARD_*.
-
void bgfx::dispatch(ViewId _id, ProgramHandle _program, IndirectBufferHandle _indirectHandle, uint32_t _start = 0, uint32_t _num = 1, uint8_t _flags = BGFX_DISCARD_ALL)
Dispatch compute indirect.
- Attention
C99’s equivalent binding is
bgfx_dispatch_indirect.
- Parameters:
_id – [in] View id.
_program – [in] Compute program.
_indirectHandle – [in] Indirect buffer.
_start – [in] First element in indirect buffer.
_num – [in] Number of dispatches.
_flags – [in] Discard or preserve states. See
BGFX_DISCARD_*.
Blit
In Views, all draw commands are executed after blit and compute commands.
-
void bgfx::blit(ViewId _id, const TextureRegion &_dst, const TextureRegion &_src)
Blit texture region between two textures.
Blit is performed on GPU, and it is ordered within the view. In views, all draw commands are executed after blit and compute commands.
Remark
The copy covers the region the two sides have in common: each side gives the origin it starts at, and the size is the smaller of the two extents. A zero
width,heightordepthextends to the rest of that mip.- Attention
Destination texture must be created with
BGFX_TEXTURE_BLIT_DSTflag.- Attention
A depth texture, or one created with
BGFX_TEXTURE_MSAA_SAMPLE, can only be blitted whole: both sides start at the origin of mips of the same size, and the copy covers the whole mip.- Attention
C99’s equivalent binding is
bgfx_blit.
- Parameters:
_id – [in] View id.
_dst – [in] Destination texture region.
_src – [in] Source texture region.
-
void bgfx::blit(ViewId _id, const BufferRegion &_dst, const BufferRegion &_src)
Blit buffer region between two buffers.
Buffer blit is performed on GPU, and it is ordered within the view, same as texture blit. In views, all draw commands are executed after blit and compute commands.
Remark
The source region gives the number of bytes copied, and the destination region gives only the offset they land at. A zero
sizecopies the rest of the source buffer.rowPitchandslicePitchare unused.- Attention
Source buffer must be created with one of
BGFX_BUFFER_COMPUTE_*, orBGFX_BUFFER_DRAW_INDIRECTflags.- Attention
Destination buffer must be created with
BGFX_BUFFER_COMPUTE_WRITE, orBGFX_BUFFER_DRAW_INDIRECTflag.- Attention
Source and destination buffer must be different.
- Attention
C99’s equivalent binding is
bgfx_blit_buffer.
- Parameters:
_id – [in] View id.
_dst – [in] Destination buffer region.
_src – [in] Source buffer region.
-
void bgfx::blit(ViewId _id, const BufferRegion &_dst, const TextureRegion &_src)
Blit texture region into buffer.
Blit is performed on GPU, and it is ordered within the view, same as texture blit. In views, all draw commands are executed after blit and compute commands.
Remark
The texture region gives the size of the copy.
BufferRegion::rowPitchandslicePitchchoose how the texels are laid out in the buffer, and 0 packs them tightly.BufferRegion::initfills in the layout the backend copies fastest, and bgfx repacks internally for any other layout.- Attention
Destination buffer must be created with
BGFX_BUFFER_COMPUTE_WRITE, orBGFX_BUFFER_DRAW_INDIRECTflag.- Attention
C99’s equivalent binding is
bgfx_blit_to_buffer.
- Parameters:
_id – [in] View id.
_dst – [in] Destination buffer region.
_src – [in] Source texture region.
-
void bgfx::blit(ViewId _id, const TextureRegion &_dst, const BufferRegion &_src)
Blit buffer contents into texture region.
Blit is performed on GPU, and it is ordered within the view, same as texture blit. In views, all draw commands are executed after blit and compute commands.
Remark
The texture region gives the size of the copy.
BufferRegion::rowPitchandslicePitchdescribe how the texels are laid out in the buffer, and 0 reads them tightly packed.BufferRegion::initfills in the layout the backend copies fastest, and bgfx repacks internally for any other layout.- Attention
Source buffer must be created with one of
BGFX_BUFFER_COMPUTE_*, orBGFX_BUFFER_DRAW_INDIRECTflags.- Attention
Destination texture must be created with
BGFX_TEXTURE_BLIT_DSTflag.- Attention
C99’s equivalent binding is
bgfx_blit_from_buffer.
- Parameters:
_id – [in] View id.
_dst – [in] Destination texture region.
_src – [in] Source buffer region.
Resources
Shaders and Programs
Note
Shaders must be compiled with offline command line tool shaderc.
-
ShaderHandle bgfx::createShader(const Memory *_mem)
Create shader from memory buffer.
Remark
Shader binary is obtained by compiling shader offline with shaderc command line tool.
- Attention
C99’s equivalent binding is
bgfx_create_shader.
- Parameters:
_mem – [in] Shader binary.
- Returns:
Shader handle.
-
uint16_t bgfx::getShaderUniforms(ShaderHandle _handle, UniformHandle *_uniforms = NULL, uint16_t _max = 0)
Returns the number of uniforms and uniform handles used inside a shader.
Remark
Only non-predefined uniforms are returned.
- Attention
C99’s equivalent binding is
bgfx_get_shader_uniforms.
- Parameters:
_handle – [in] Shader handle.
_uniforms – [out] UniformHandle array where data will be stored.
_max – [in] Maximum capacity of array.
- Returns:
Number of uniforms used by shader.
-
void bgfx::destroy(ShaderHandle _handle)
Destroy shader.
Remark
Once a shader program is created with _handle, it is safe to destroy that shader.
- Attention
C99’s equivalent binding is
bgfx_destroy_shader.
- Parameters:
_handle – [in] Shader handle.
-
ProgramHandle bgfx::createProgram(ShaderHandle _vsh, ShaderHandle _fsh, bool _destroyShaders = false)
Create program with vertex and fragment shaders.
- Attention
C99’s equivalent binding is
bgfx_create_program.
- Parameters:
_vsh – [in] Vertex shader.
_fsh – [in] Fragment shader.
_destroyShaders – [in] If true, shaders will be destroyed when program is destroyed.
- Returns:
Program handle if vertex shader output and fragment shader input are matching, otherwise returns invalid program handle.
-
ProgramHandle bgfx::createProgram(ShaderHandle _csh, bool _destroyShaders = false)
Create program with compute shader.
- Attention
C99’s equivalent binding is
bgfx_create_compute_program.
- Parameters:
_csh – [in] Compute shader.
_destroyShaders – [in] If true, shaders will be destroyed when program is destroyed.
- Returns:
Program handle.
-
void bgfx::destroy(ProgramHandle _handle)
Destroy program.
- Attention
C99’s equivalent binding is
bgfx_destroy_program.
- Parameters:
_handle – [in] Program handle.
Uniforms
-
struct UniformType
Uniform type enum.
- Attention
C99’s equivalent binding is
bgfx_uniform_type_t.
-
struct UniformFreq
Uniform frequency enum.
- Attention
C99’s equivalent binding is
bgfx_uniform_freq_t.
-
struct UniformInfo
Uniform info.
- Attention
C99’s equivalent binding is
bgfx_uniform_info_t.
Public Members
-
char name[256]
Uniform name.
-
UniformType::Enum type
Uniform type.
-
uint16_t num
Number of elements in array.
-
UniformHandle bgfx::createUniform(const char *_name, UniformType::Enum _type, uint16_t _num = 1)
Create shader uniform parameter.
Remark
Uniform names are unique. It’s valid to call
bgfx::createUniformmultiple 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 ofbgfx::destroyUniformmust be called to properly destroy the uniform.Predefined uniforms (declared in
bgfx_shader.sh):u_viewRect vec4(x, y, width, height)- view rectangle for current view, in pixels.u_viewTexel vec4(1.0/width, 1.0/height, undef, undef)- inverse width and heightu_view mat4- view matrixu_invView mat4- inverted view matrixu_proj mat4- projection matrixu_invProj mat4- inverted projection matrixu_viewProj mat4- concatenated view projection matrixu_invViewProj mat4- concatenated inverted view projection matrixu_model mat4[BGFX_CONFIG_MAX_BONES]- array of model matrices.u_modelView mat4- concatenated model view matrix, only first model matrix from array is used.u_invModelView mat4- inverted concatenated model view matrix.u_modelViewProj mat4- concatenated model view projection matrix.u_alphaRef float- alpha reference value for alpha test.
- Attention
C99’s equivalent binding is
bgfx_create_uniform.
- Parameters:
_name – [in] Uniform name in shader.
_type – [in] Type of uniform (See:
bgfx::UniformType)._num – [in] Number of elements in array.
- Returns:
Handle to uniform object.
-
UniformHandle bgfx::createUniform(const char *_name, UniformFreq::Enum _freq, UniformType::Enum _type, uint16_t _num = 1)
Create shader uniform parameter.
Remark
Uniform names are unique. It’s valid to call
bgfx::createUniformmultiple 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 ofbgfx::destroyUniformmust be called to properly destroy the uniform.Predefined uniforms (declared in
bgfx_shader.sh):u_viewRect vec4(x, y, width, height)- view rectangle for current view, in pixels.u_viewTexel vec4(1.0/width, 1.0/height, undef, undef)- inverse width and heightu_view mat4- view matrixu_invView mat4- inverted view matrixu_proj mat4- projection matrixu_invProj mat4- inverted projection matrixu_viewProj mat4- concatenated view projection matrixu_invViewProj mat4- concatenated inverted view projection matrixu_model mat4[BGFX_CONFIG_MAX_BONES]- array of model matrices.u_modelView mat4- concatenated model view matrix, only first model matrix from array is used.u_invModelView mat4- inverted concatenated model view matrix.u_modelViewProj mat4- concatenated model view projection matrix.u_alphaRef float- alpha reference value for alpha test.
- Attention
C99’s equivalent binding is
bgfx_create_uniform_with_freq.
- Parameters:
_name – [in] Uniform name in shader.
_freq – [in] Uniform change frequency (See:
bgfx::UniformFreq)._type – [in] Type of uniform (See:
bgfx::UniformType)._num – [in] Number of elements in array.
- Returns:
Handle to uniform object.
-
void bgfx::getUniformInfo(UniformHandle _handle, UniformInfo &_info)
Retrieve uniform info.
- Attention
C99’s equivalent binding is
bgfx_get_uniform_info.
- Parameters:
_handle – [in] Handle to uniform object.
_info – [out] Uniform info.
-
void bgfx::destroy(UniformHandle _handle)
Destroy shader uniform parameter.
- Attention
C99’s equivalent binding is
bgfx_destroy_uniform.
- Parameters:
_handle – [in] Handle to uniform object.
Vertex Buffers
-
struct Attrib
Vertex attribute enum.
- Attention
C99’s equivalent binding is
bgfx_attrib_t.
Public Types
-
enum Enum
Corresponds to vertex shader attribute.
Values:
-
enumerator Position
a_position
-
enumerator Normal
a_normal
-
enumerator Tangent
a_tangent
-
enumerator Bitangent
a_bitangent
-
enumerator Color0
a_color0
-
enumerator Color1
a_color1
-
enumerator Color2
a_color2
-
enumerator Color3
a_color3
-
enumerator Indices
a_indices
-
enumerator Weight
a_weight
-
enumerator TexCoord0
a_texcoord0
-
enumerator TexCoord1
a_texcoord1
-
enumerator TexCoord2
a_texcoord2
-
enumerator TexCoord3
a_texcoord3
-
enumerator TexCoord4
a_texcoord4
-
enumerator TexCoord5
a_texcoord5
-
enumerator TexCoord6
a_texcoord6
-
enumerator TexCoord7
a_texcoord7
-
enumerator TexCoord8
a_texcoord8
-
enumerator TexCoord9
a_texcoord9
-
enumerator TexCoord10
a_texcoord10
-
enumerator TexCoord11
a_texcoord11
-
enumerator TexCoord12
a_texcoord12
-
enumerator TexCoord13
a_texcoord13
-
enumerator TexCoord14
a_texcoord14
-
enumerator TexCoord15
a_texcoord15
-
enumerator Count
-
enumerator Position
-
struct AttribType
Vertex attribute type enum.
- Attention
C99’s equivalent binding is
bgfx_attrib_type_t.
Public Types
-
enum Enum
Attribute types:
Values:
-
enumerator Int8
Int8.
-
enumerator Uint8
Uint8.
-
enumerator Uint10
Uint10, availability depends on:
BGFX_CAPS_VERTEX_ATTRIB_UINT10.
-
enumerator Int16
Int16.
-
enumerator Uint16
Uint16.
-
enumerator Half
Half.
-
enumerator Float
Float.
-
enumerator Int32
Int32.
-
enumerator Uint32
Uint32.
-
enumerator Count
-
enumerator Int8
-
struct VertexLayout
Vertex layout.
- Attention
C99’s equivalent binding is
bgfx_vertex_layout_t.
Public Functions
-
VertexLayout &begin(RendererType::Enum _rendererType = RendererType::Noop)
Start VertexLayout.
- Attention
C99’s equivalent binding is
bgfx_vertex_layout_begin.
- Parameters:
_rendererType – [in] Renderer backend type. See:
bgfx::RendererType- Returns:
Returns itself.
-
VertexLayout &add(Attrib::Enum _attrib, uint8_t _num, AttribType::Enum _type, bool _normalized = false, bool _asInt = false)
Add attribute to VertexLayout.
Remark
Must be called between begin/end.
- Attention
C99’s equivalent binding is
bgfx_vertex_layout_add.
- Parameters:
_attrib – [in] Attribute semantics. See:
bgfx::Attrib_num – [in] Number of elements 1, 2, 3 or 4.
_type – [in] Element type.
_normalized – [in] When using fixed point AttribType (f.e. Uint8) value will be normalized for vertex shader usage. When normalized is set to true, AttribType::Uint8 value in range 0-255 will be in range 0.0-1.0 in vertex shader.
_asInt – [in] Packaging rule for vertexPack, vertexUnpack, and vertexConvert for AttribType::Uint8 and AttribType::Int16. Unpacking code must be implemented inside vertex shader.
- Returns:
Returns itself.
-
void decode(Attrib::Enum _attrib, uint8_t &_num, AttribType::Enum &_type, bool &_normalized, bool &_asInt) const
Decode attribute.
- Attention
C99’s equivalent binding is
bgfx_vertex_layout_decode.
- Parameters:
_attrib – [in] Attribute semantics. See:
bgfx::Attrib_num – [out] Number of elements.
_type – [out] Element type.
_normalized – [out] Attribute is normalized.
_asInt – [out] Attribute is packed as int.
-
inline bool has(Attrib::Enum _attrib) const
Returns
trueif VertexLayout contains attribute.- Parameters:
_attrib – [in] Attribute semantics. See:
bgfx::Attrib- Returns:
True if VertexLayout contains attribute.
-
VertexLayout &skip(uint8_t _num)
Skip
_numbytes in vertex stream.- Attention
C99’s equivalent binding is
bgfx_vertex_layout_skip.
- Parameters:
_num – [in] Number of bytes to skip.
- Returns:
Returns itself.
-
void end()
End VertexLayout.
- Attention
C99’s equivalent binding is
bgfx_vertex_layout_end.
-
inline uint16_t getOffset(Attrib::Enum _attrib) const
Returns relative attribute offset from the vertex.
- Parameters:
_attrib – [in] Attribute semantics. See:
bgfx::Attrib- Returns:
Relative attribute offset from the vertex.
-
inline uint16_t getStride() const
Returns vertex stride.
- Returns:
Vertex stride.
-
inline uint32_t getSize(uint32_t _num) const
Returns size of vertex buffer for number of vertices.
- Parameters:
_num – [in] Number of vertices.
- Returns:
Size of vertex buffer for number of vertices.
-
VertexLayoutHandle bgfx::createVertexLayout(const VertexLayout &_layout)
Create vertex layout. Vertex layouts are used to describe the format of vertex data.
- Attention
C99’s equivalent binding is
bgfx_create_vertex_layout.
- Parameters:
_layout – [in] Vertex layout.
-
void bgfx::destroy(VertexLayoutHandle _layoutHandle)
Destroy vertex layout.
- Attention
C99’s equivalent binding is
bgfx_destroy_vertex_layout.
- Parameters:
_layoutHandle – [in] Vertex layout handle.
-
VertexBufferHandle bgfx::createVertexBuffer(const Memory *_mem, const VertexLayout &_layout, uint16_t _flags = BGFX_BUFFER_NONE)
Create static vertex buffer.
- Attention
C99’s equivalent binding is
bgfx_create_vertex_buffer.
- Parameters:
_mem – [in] Vertex buffer data.
_layout – [in] Vertex layout.
_flags – [in] Buffer creation flags.
BGFX_BUFFER_NONE- No flags.BGFX_BUFFER_COMPUTE_READ- Buffer will be read from by compute shader.BGFX_BUFFER_COMPUTE_WRITE- Buffer will be written into by compute shader. When buffer is created withBGFX_BUFFER_COMPUTE_WRITEflag it cannot be updated from CPU.BGFX_BUFFER_COMPUTE_READ_WRITE- Buffer will be used for read/write by compute shader.BGFX_BUFFER_ALLOW_RESIZE- Buffer will resize on buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.BGFX_BUFFER_INDEX32- Buffer is using 32-bit indices. This flag has effect only on index buffers.
- Returns:
Static vertex buffer handle.
-
void bgfx::setName(VertexBufferHandle _handle, const char *_name, int32_t _len = INT32_MAX)
Set static vertex buffer debug name.
- Attention
C99’s equivalent binding is
bgfx_set_vertex_buffer_name.
- Parameters:
_handle – [in] Static vertex buffer handle.
_name – [in] Static vertex buffer name.
_len – [in] Static vertex buffer name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.
-
void bgfx::destroy(VertexBufferHandle _handle)
Destroy static vertex buffer.
- Attention
C99’s equivalent binding is
bgfx_destroy_vertex_buffer.
- Parameters:
_handle – [in] Static vertex buffer handle.
-
DynamicVertexBufferHandle bgfx::createDynamicVertexBuffer(uint32_t _num, const VertexLayout &_layout, uint16_t _flags = BGFX_BUFFER_NONE)
Create empty dynamic vertex buffer.
- Attention
C99’s equivalent binding is
bgfx_create_dynamic_vertex_buffer.
- Parameters:
_num – [in] Number of vertices.
_layout – [in] Vertex layout.
_flags – [in] Buffer creation flags.
BGFX_BUFFER_NONE- No flags.BGFX_BUFFER_COMPUTE_READ- Buffer will be read from by compute shader.BGFX_BUFFER_COMPUTE_WRITE- Buffer will be written into by compute shader. When buffer is created withBGFX_BUFFER_COMPUTE_WRITEflag it cannot be updated from CPU.BGFX_BUFFER_COMPUTE_READ_WRITE- Buffer will be used for read/write by compute shader.BGFX_BUFFER_ALLOW_RESIZE- Buffer will resize on buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.BGFX_BUFFER_INDEX32- Buffer is using 32-bit indices. This flag has effect only on index buffers.
- Returns:
Dynamic vertex buffer handle.
-
DynamicVertexBufferHandle bgfx::createDynamicVertexBuffer(const Memory *_mem, const VertexLayout &_layout, uint16_t _flags = BGFX_BUFFER_NONE)
Create dynamic vertex buffer and initialize it.
- Attention
C99’s equivalent binding is
bgfx_create_dynamic_vertex_buffer_mem.
- Parameters:
_mem – [in] Vertex buffer data.
_layout – [in] Vertex layout.
_flags – [in] Buffer creation flags.
BGFX_BUFFER_NONE- No flags.BGFX_BUFFER_COMPUTE_READ- Buffer will be read from by compute shader.BGFX_BUFFER_COMPUTE_WRITE- Buffer will be written into by compute shader. When buffer is created withBGFX_BUFFER_COMPUTE_WRITEflag it cannot be updated from CPU.BGFX_BUFFER_COMPUTE_READ_WRITE- Buffer will be used for read/write by compute shader.BGFX_BUFFER_ALLOW_RESIZE- Buffer will resize on buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.BGFX_BUFFER_INDEX32- Buffer is using 32-bit indices. This flag has effect only on index buffers.
- Returns:
Dynamic vertex buffer handle.
-
void bgfx::update(DynamicVertexBufferHandle _handle, uint32_t _startVertex, const Memory *_mem)
Update dynamic vertex buffer.
- Attention
C99’s equivalent binding is
bgfx_update_dynamic_vertex_buffer.
- Parameters:
_handle – [in] Dynamic vertex buffer handle.
_startVertex – [in] Start vertex.
_mem – [in] Vertex buffer data.
-
void bgfx::destroy(DynamicVertexBufferHandle _handle)
Destroy dynamic vertex buffer.
- Attention
C99’s equivalent binding is
bgfx_destroy_dynamic_vertex_buffer.
- Parameters:
_handle – [in] Dynamic vertex buffer handle.
-
uint32_t bgfx::getAvailTransientVertexBuffer(uint32_t _num, const VertexLayout &_layout)
Returns number of requested or maximum available vertices.
- Attention
C99’s equivalent binding is
bgfx_get_avail_transient_vertex_buffer.
- Parameters:
_num – [in] Number of required vertices.
_layout – [in] Vertex layout.
- Returns:
Number of requested or maximum available vertices.
-
void bgfx::allocTransientVertexBuffer(TransientVertexBuffer *_tvb, uint32_t _num, const VertexLayout &_layout)
Allocate transient vertex buffer.
- Attention
C99’s equivalent binding is
bgfx_alloc_transient_vertex_buffer.
- Parameters:
_tvb – [out] TransientVertexBuffer structure will be filled, and will be valid for the duration of frame, and can be reused for multiple draw calls.
_num – [in] Number of vertices to allocate.
_layout – [in] Vertex layout.
Index Buffers
-
IndexBufferHandle bgfx::createIndexBuffer(const Memory *_mem, uint16_t _flags = BGFX_BUFFER_NONE)
Create static index buffer.
- Attention
C99’s equivalent binding is
bgfx_create_index_buffer.
- Parameters:
_mem – [in] Index buffer data.
_flags – [in] Buffer creation flags.
BGFX_BUFFER_NONE- No flags.BGFX_BUFFER_COMPUTE_READ- Buffer will be read from by compute shader.BGFX_BUFFER_COMPUTE_WRITE- Buffer will be written into by compute shader. When buffer is created withBGFX_BUFFER_COMPUTE_WRITEflag it cannot be updated from CPU.BGFX_BUFFER_COMPUTE_READ_WRITE- Buffer will be used for read/write by compute shader.BGFX_BUFFER_ALLOW_RESIZE- Buffer will resize on buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.BGFX_BUFFER_INDEX32- Buffer is using 32-bit indices. This flag has effect only on index buffers.
-
void bgfx::setName(IndexBufferHandle _handle, const char *_name, int32_t _len = INT32_MAX)
Set static index buffer debug name.
- Attention
C99’s equivalent binding is
bgfx_set_index_buffer_name.
- Parameters:
_handle – [in] Static index buffer handle.
_name – [in] Static index buffer name.
_len – [in] Static index buffer name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.
-
void bgfx::destroy(IndexBufferHandle _handle)
Destroy static index buffer.
- Attention
C99’s equivalent binding is
bgfx_destroy_index_buffer.
- Parameters:
_handle – [in] Static index buffer handle.
-
DynamicIndexBufferHandle bgfx::createDynamicIndexBuffer(uint32_t _num, uint16_t _flags = BGFX_BUFFER_NONE)
Create empty dynamic index buffer.
- Attention
C99’s equivalent binding is
bgfx_create_dynamic_index_buffer.
- Parameters:
_num – [in] Number of indices.
_flags – [in] Buffer creation flags.
BGFX_BUFFER_NONE- No flags.BGFX_BUFFER_COMPUTE_READ- Buffer will be read from by compute shader.BGFX_BUFFER_COMPUTE_WRITE- Buffer will be written into by compute shader. When buffer is created withBGFX_BUFFER_COMPUTE_WRITEflag it cannot be updated from CPU.BGFX_BUFFER_COMPUTE_READ_WRITE- Buffer will be used for read/write by compute shader.BGFX_BUFFER_ALLOW_RESIZE- Buffer will resize on buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.BGFX_BUFFER_INDEX32- Buffer is using 32-bit indices. This flag has effect only on index buffers.
- Returns:
Dynamic index buffer handle.
-
DynamicIndexBufferHandle bgfx::createDynamicIndexBuffer(const Memory *_mem, uint16_t _flags = BGFX_BUFFER_NONE)
Create a dynamic index buffer and initialize it.
- Attention
C99’s equivalent binding is
bgfx_create_dynamic_index_buffer_mem.
- Parameters:
_mem – [in] Index buffer data.
_flags – [in] Buffer creation flags.
BGFX_BUFFER_NONE- No flags.BGFX_BUFFER_COMPUTE_READ- Buffer will be read from by compute shader.BGFX_BUFFER_COMPUTE_WRITE- Buffer will be written into by compute shader. When buffer is created withBGFX_BUFFER_COMPUTE_WRITEflag it cannot be updated from CPU.BGFX_BUFFER_COMPUTE_READ_WRITE- Buffer will be used for read/write by compute shader.BGFX_BUFFER_ALLOW_RESIZE- Buffer will resize on buffer update if a different amount of data is passed. If this flag is not specified, and more data is passed on update, the buffer will be trimmed to fit the existing buffer size. This flag has effect only on dynamic buffers.BGFX_BUFFER_INDEX32- Buffer is using 32-bit indices. This flag has effect only on index buffers.
- Returns:
Dynamic index buffer handle.
-
void bgfx::update(DynamicIndexBufferHandle _handle, uint32_t _startIndex, const Memory *_mem)
Update dynamic index buffer.
- Attention
C99’s equivalent binding is
bgfx_update_dynamic_index_buffer.
- Parameters:
_handle – [in] Dynamic index buffer handle.
_startIndex – [in] Start index.
_mem – [in] Index buffer data.
-
void bgfx::destroy(DynamicIndexBufferHandle _handle)
Destroy dynamic index buffer.
- Attention
C99’s equivalent binding is
bgfx_destroy_dynamic_index_buffer.
- Parameters:
_handle – [in] Dynamic index buffer handle.
-
uint32_t bgfx::getAvailTransientIndexBuffer(uint32_t _num, bool _index32 = false)
Returns number of requested or maximum available indices.
- Attention
C99’s equivalent binding is
bgfx_get_avail_transient_index_buffer.
- Parameters:
_num – [in] Number of required indices.
_index32 – [in] Set to
trueif input indices will be 32-bit.
- Returns:
Number of requested or maximum available indices.
-
void bgfx::allocTransientIndexBuffer(TransientIndexBuffer *_tib, uint32_t _num, bool _index32 = false)
Allocate transient index buffer.
- Attention
C99’s equivalent binding is
bgfx_alloc_transient_index_buffer.
- Parameters:
_tib – [out] TransientIndexBuffer structure will be filled, and will be valid for the duration of frame, and can be reused for multiple draw calls.
_num – [in] Number of indices to allocate.
_index32 – [in] Set to
trueif input indices will be 32-bit.
Textures
-
BGFX_TEXTURE_NONE
-
BGFX_TEXTURE_MSAA_SAMPLE
Texture will be used for MSAA sampling.
-
BGFX_TEXTURE_RT
Render target no MSAA.
-
BGFX_TEXTURE_COMPUTE_WRITE
Texture will be used for compute write.
-
BGFX_TEXTURE_SRGB
Sample texture as sRGB.
-
BGFX_TEXTURE_BLIT_DST
Texture will be used as blit destination.
-
BGFX_TEXTURE_READ_BACK
Texture will be used for read back from GPU.
-
BGFX_TEXTURE_EXTERNAL_SHARED
Texture is shared with other device or other process.
-
BGFX_TEXTURE_SRGB_MUTABLE
Texture may be sampled and rendered with either sRGB-ness, not just the one implied by its format. Every bind and attachment must then state the encoding it wants (see
BGFX_SAMPLER_SRGB,BGFX_ATTACHMENT_SRGB). Costs nothing until used, but may disable texture compression on some hardware.
-
BGFX_TEXTURE_RT_WRITE_ONLY
Render target will be used for writing.
-
struct TextureFormat
Texture format enum.
Notation:
RGBA16S ^ ^ ^ | | +-- [ ]Unorm | | [F]loat | | [S]norm | | [I]nt | | [U]int | +---- Number of bits per component +-------- Components
- Attention
Availability depends on Caps (see: formats).
- Attention
C99’s equivalent binding is
bgfx_texture_format_t.
Public Types
-
enum Enum
Texture formats:
Values:
-
enumerator BC1
Block Compression 1. 5-bit R, 6-bit G, 5-bit B, 1-bit A. 4 BPP.
-
enumerator BC2
Block Compression 2. 5-bit R, 6-bit G, 5-bit B, 4-bit explicit A. 8 BPP.
-
enumerator BC3
Block Compression 3. 5-bit R, 6-bit G, 5-bit B, 8-bit interpolated A. 8 BPP.
-
enumerator BC4
Block Compression 4. Single 8-bit red channel, unsigned normalized. 4 BPP.
-
enumerator BC4S
Block Compression 4. Single 8-bit red channel, signed normalized. 4 BPP.
-
enumerator BC5
Block Compression 5. Two 8-bit channels (RG), unsigned normalized. 8 BPP.
-
enumerator BC5S
Block Compression 5. Two 8-bit channels (RG), signed normalized. 8 BPP.
-
enumerator BC6H
Block Compression 6H. Three 16-bit floating-point channels (RGB), HDR. 8 BPP.
-
enumerator BC6HU
Block Compression 6H. Three 16-bit unsigned floating-point channels (RGB), HDR. 8 BPP.
-
enumerator BC7
RGB 4-7 bits per color channel, 0-8 bits alpha. Block Compression 7. High-quality RGBA, 4-7 bits per color, 0-8 bits alpha. 8 BPP.
-
enumerator ETC1
Ericsson Texture Compression 1. 8-bit per channel RGB. 4 BPP.
-
enumerator ETC2
Ericsson Texture Compression 2. 8-bit per channel RGB. 4 BPP.
-
enumerator ETC2A
Ericsson Texture Compression 2 with full alpha. 8-bit per channel RGBA. 8 BPP.
-
enumerator ETC2A1
Ericsson Texture Compression 2 with 1-bit punch-through alpha. 4 BPP.
-
enumerator EACR11
ETC2 Alpha Compression, single 11-bit red channel, unsigned normalized. 4 BPP.
-
enumerator EACR11S
ETC2 Alpha Compression, single 11-bit red channel, signed normalized. 4 BPP.
-
enumerator EACRG11
ETC2 Alpha Compression, two 11-bit channels (RG), unsigned normalized. 8 BPP.
-
enumerator EACRG11S
ETC2 Alpha Compression, two 11-bit channels (RG), signed normalized. 8 BPP.
-
enumerator PTC12
PowerVR Texture Compression v1. 3-channel RGB. 2 BPP.
-
enumerator PTC14
PowerVR Texture Compression v1. 3-channel RGB. 4 BPP.
-
enumerator PTC12A
PowerVR Texture Compression v1. 4-channel RGBA. 2 BPP.
-
enumerator PTC14A
PowerVR Texture Compression v1. 4-channel RGBA. 4 BPP.
-
enumerator PTC22
PowerVR Texture Compression v2. 4-channel RGBA. 2 BPP.
-
enumerator PTC24
PowerVR Texture Compression v2. 4-channel RGBA. 4 BPP.
-
enumerator ATC
AMD Texture Compression. 3-channel RGB. 4 BPP.
-
enumerator ATCE
AMD Texture Compression with explicit alpha. 4-channel RGBA. 8 BPP.
-
enumerator ATCI
AMD Texture Compression with interpolated alpha. 4-channel RGBA. 8 BPP.
-
enumerator ASTC4x4
Adaptive Scalable Texture Compression, 4x4 block, RGBA. 8.00 BPP.
-
enumerator ASTC5x4
Adaptive Scalable Texture Compression, 5x4 block, RGBA. 6.40 BPP.
-
enumerator ASTC5x5
Adaptive Scalable Texture Compression, 5x5 block, RGBA. 5.12 BPP.
-
enumerator ASTC6x5
Adaptive Scalable Texture Compression, 6x5 block, RGBA. 4.27 BPP.
-
enumerator ASTC6x6
Adaptive Scalable Texture Compression, 6x6 block, RGBA. 3.56 BPP.
-
enumerator ASTC8x5
Adaptive Scalable Texture Compression, 8x5 block, RGBA. 3.20 BPP.
-
enumerator ASTC8x6
Adaptive Scalable Texture Compression, 8x6 block, RGBA. 2.67 BPP.
-
enumerator ASTC8x8
Adaptive Scalable Texture Compression, 8x8 block, RGBA. 2.00 BPP.
-
enumerator ASTC10x5
Adaptive Scalable Texture Compression, 10x5 block, RGBA. 2.56 BPP.
-
enumerator ASTC10x6
Adaptive Scalable Texture Compression, 10x6 block, RGBA. 2.13 BPP.
-
enumerator ASTC10x8
Adaptive Scalable Texture Compression, 10x8 block, RGBA. 1.60 BPP.
-
enumerator ASTC10x10
Adaptive Scalable Texture Compression, 10x10 block, RGBA. 1.28 BPP.
-
enumerator ASTC12x10
Adaptive Scalable Texture Compression, 12x10 block, RGBA. 1.07 BPP.
-
enumerator ASTC12x12
Adaptive Scalable Texture Compression, 12x12 block, RGBA. 0.89 BPP.
-
enumerator Unknown
Compressed formats above.
-
enumerator R1
1-bit single-channel red. Monochrome, 1-bit per pixel. 1 BPP.
-
enumerator A8
8-bit single-channel alpha, unsigned normalized. 8 BPP.
-
enumerator R8
8-bit single-channel red, unsigned normalized. 8 BPP.
-
enumerator R8I
8-bit single-channel red, signed integer. 8 BPP.
-
enumerator R8U
8-bit single-channel red, unsigned integer. 8 BPP.
-
enumerator R8S
8-bit single-channel red, signed normalized. 8 BPP.
-
enumerator R16
16-bit single-channel red, unsigned normalized. 16 BPP.
-
enumerator R16I
16-bit single-channel red, signed integer. 16 BPP.
-
enumerator R16U
16-bit single-channel red, unsigned integer. 16 BPP.
-
enumerator R16F
16-bit single-channel red, half-precision floating point. 16 BPP.
-
enumerator R16S
16-bit single-channel red, signed normalized. 16 BPP.
-
enumerator R32I
32-bit single-channel red, signed integer. 32 BPP.
-
enumerator R32U
32-bit single-channel red, unsigned integer. 32 BPP.
-
enumerator R32F
32-bit single-channel red, full-precision floating point. 32 BPP.
-
enumerator RG8
Two 8-bit channels (red, green), unsigned normalized. 16 BPP.
-
enumerator RG8I
Two 8-bit channels (red, green), signed integer. 16 BPP.
-
enumerator RG8U
Two 8-bit channels (red, green), unsigned integer. 16 BPP.
-
enumerator RG8S
Two 8-bit channels (red, green), signed normalized. 16 BPP.
-
enumerator RG16
Two 16-bit channels (red, green), unsigned normalized. 32 BPP.
-
enumerator RG16I
Two 16-bit channels (red, green), signed integer. 32 BPP.
-
enumerator RG16U
Two 16-bit channels (red, green), unsigned integer. 32 BPP.
-
enumerator RG16F
Two 16-bit channels (red, green), half-precision floating point. 32 BPP.
-
enumerator RG16S
Two 16-bit channels (red, green), signed normalized. 32 BPP.
-
enumerator RG32I
Two 32-bit channels (red, green), signed integer. 64 BPP.
-
enumerator RG32U
Two 32-bit channels (red, green), unsigned integer. 64 BPP.
-
enumerator RG32F
Two 32-bit channels (red, green), full-precision floating point. 64 BPP.
-
enumerator RGB8
Three 8-bit channels (red, green, blue), unsigned normalized. 24 BPP.
-
enumerator RGB8I
Three 8-bit channels (red, green, blue), signed integer. 24 BPP.
-
enumerator RGB8U
Three 8-bit channels (red, green, blue), unsigned integer. 24 BPP.
-
enumerator RGB8S
Three 8-bit channels (red, green, blue), signed normalized. 24 BPP.
-
enumerator RGB9E5F
Shared-exponent RGB. 9 bits per RGB channel with a shared 5-bit exponent, floating point. 32 BPP.
-
enumerator BGRA8
Four 8-bit channels (blue, green, red, alpha), unsigned normalized. BGRA byte order. 32 BPP.
-
enumerator RGBA8
Four 8-bit channels (red, green, blue, alpha), unsigned normalized. 32 BPP.
-
enumerator RGBA8I
Four 8-bit channels (red, green, blue, alpha), signed integer. 32 BPP.
-
enumerator RGBA8U
Four 8-bit channels (red, green, blue, alpha), unsigned integer. 32 BPP.
-
enumerator RGBA8S
Four 8-bit channels (red, green, blue, alpha), signed normalized. 32 BPP.
-
enumerator RGBA16
Four 16-bit channels (red, green, blue, alpha), unsigned normalized. 64 BPP.
-
enumerator RGBA16I
Four 16-bit channels (red, green, blue, alpha), signed integer. 64 BPP.
-
enumerator RGBA16U
Four 16-bit channels (red, green, blue, alpha), unsigned integer. 64 BPP.
-
enumerator RGBA16F
Four 16-bit channels (red, green, blue, alpha), half-precision floating point. 64 BPP.
-
enumerator RGBA16S
Four 16-bit channels (red, green, blue, alpha), signed normalized. 64 BPP.
-
enumerator RGBA32I
Four 32-bit channels (red, green, blue, alpha), signed integer. 128 BPP.
-
enumerator RGBA32U
Four 32-bit channels (red, green, blue, alpha), unsigned integer. 128 BPP.
-
enumerator RGBA32F
Four 32-bit channels (red, green, blue, alpha), full-precision floating point. 128 BPP.
-
enumerator B5G6R5
Packed 16-bit, 5-bit blue, 6-bit green, 5-bit red. BGR byte order, unsigned normalized. 16 BPP.
-
enumerator R5G6B5
Packed 16-bit, 5-bit red, 6-bit green, 5-bit blue. RGB byte order, unsigned normalized. 16 BPP.
-
enumerator BGRA4
Packed 16-bit, 4-bit per channel (blue, green, red, alpha). BGRA byte order, unsigned normalized. 16 BPP.
-
enumerator RGBA4
Packed 16-bit, 4-bit per channel (red, green, blue, alpha), unsigned normalized. 16 BPP.
-
enumerator BGR5A1
Packed 16-bit, 5-bit blue, 5-bit green, 5-bit red, 1-bit alpha. BGRA byte order, unsigned normalized. 16 BPP.
-
enumerator RGB5A1
Packed 16-bit, 5-bit red, 5-bit green, 5-bit blue, 1-bit alpha, unsigned normalized. 16 BPP.
-
enumerator RGB10A2
Packed 32-bit, 10-bit red, 10-bit green, 10-bit blue, 2-bit alpha, unsigned normalized. 32 BPP.
-
enumerator RGB10A2U
Packed 32-bit, 10-bit red, 10-bit green, 10-bit blue, 2-bit alpha, unsigned integer. 32 BPP.
-
enumerator RG11B10F
Packed 32-bit, 11-bit red, 11-bit green, 10-bit blue, unsigned floating point. No alpha. 32 BPP.
-
enumerator UnknownDepth
Depth formats below.
-
enumerator D16
16-bit depth, unsigned normalized. 16 BPP.
-
enumerator D24
24-bit depth, unsigned normalized (stored as 32-bit with 8 bits unused). 32 BPP.
-
enumerator D24S8
24-bit depth, unsigned normalized, with 8-bit stencil. 32 BPP.
-
enumerator D32
32-bit depth, unsigned normalized. 32 BPP.
-
enumerator D16F
16-bit depth, floating point. 16 BPP.
-
enumerator D24F
24-bit depth, floating point (stored as 32-bit). 32 BPP.
-
enumerator D32F
32-bit depth, floating point. 32 BPP.
-
enumerator D32FS8
32-bit depth, floating point, with 8-bit stencil (stored as 64-bit). 64 BPP.
-
enumerator D0S8
8-bit stencil only, no depth. 8 BPP.
-
enumerator Count
-
enumerator BC1
-
struct TextureRegion
Region of a texture, used as the source or destination of a blit, or as the region handed to
bgfx::read.Every field defaults to zero, and zero always means “the natural whole”.
{ .handle = tex }therefore addresses all of mip 0.- Attention
C99’s equivalent binding is
bgfx_texture_region_t.
Public Functions
-
void init(TextureHandle _handle, uint16_t _x = 0, uint16_t _y = 0, uint16_t _width = 0, uint16_t _height = 0)
Fill in the region of a plain 2D texture.
mip,zanddepthare left at zero, which addresses mip 0 of the only slice a 2D texture has.- Attention
C99’s equivalent binding is
bgfx_texture_region_init.
- Parameters:
_handle – [in] Texture handle.
_x – [in] X position of the region.
_y – [in] Y position of the region.
_width – [in] Width of the region. 0 uses the rest of the mip from
_x._height – [in] Height of the region. 0 uses the rest of the mip from
_y.
Public Members
-
TextureHandle handle = BGFX_INVALID_HANDLE
Texture handle.
-
uint8_t mip = 0
Mip level.
-
uint16_t x = 0
X position of the region.
-
uint16_t y = 0
Y position of the region.
-
uint16_t z = 0
If texture is 2D this should be 0. If the texture is a cube map this is the cube face, for a 2D array it is the layer, and for a 3D texture it is the Z position.
-
uint16_t width = 0
Width of the region. 0 uses the rest of the mip from
x.
-
uint16_t height = 0
Height of the region. 0 uses the rest of the mip from
y.
-
uint16_t depth = 0
Depth of the region for a 3D texture, or the number of layers or cube faces otherwise. 0 uses the rest from
z.
-
struct TextureInfo
Texture info.
- Attention
C99’s equivalent binding is
bgfx_texture_info_t.
Public Members
-
TextureFormat::Enum format
Texture format.
-
uint32_t storageSize
Total amount of bytes required to store texture.
-
uint16_t width
Texture width.
-
uint16_t height
Texture height.
-
uint16_t depth
Texture depth.
-
uint16_t numLayers
Number of layers in texture array.
-
uint8_t numMips
Number of MIP maps.
-
uint8_t bitsPerPixel
Format bits per pixel.
-
bool cubeMap
Texture is cubemap.
-
struct VideoDecoderInit
Video decoder initialization. Serialized into the Memory passed to
createTexture2D. When the memory blob begins withmagic, bgfx infers the texture is a video decode destination (the caller need not set any extra texture flag). Everything else the renderer needs about the stream (chroma format, bit depth, profile, level, coded dimensions, DPB layout, color metadata) is parsed out of the codec parameter sets at create time.- Attention
C99’s equivalent binding is
bgfx_video_decoder_init_t.
Public Members
-
uint32_t magic
Structure magic. Must be ‘BX_MAKEFOURCC(‘V’, ‘D’, ‘I’, 0x0)`.
-
VideoCodec::Enum codec
Video codec. See:
VideoCodec::Enum.
-
const uint8_t *parameterSets
Codec parameter sets (Annex B for H.264/H.265, OBUs for AV1).
-
uint32_t parameterSetsSize
Parameter sets size in bytes.
-
uint32_t cachedAuBytes
Soft cap (in bytes) on the streaming access-unit FIFO (when
BGFX_VIDEO_DECODER_INIT_RETAINis NOT set). 0 selects the default. Ignored in RETAIN mode (the retain cache is unbounded).
-
uint8_t flags
Decoder lifetime flags. See:
BGFX_VIDEO_DECODER_INIT_*.
-
struct VideoDecoderAu
One access unit entry inside a
VideoDecoderFramebatch. The bitstream for the AU lives at offsetΣ aus[0..ii].sizeinside the frame’sbitstreambuffer (access units are stored back-to-back in decode / submission order).- Attention
C99’s equivalent binding is
bgfx_video_decoder_au_t.
-
struct VideoDecoderFrame
Video decoder per-frame submission. Serialized into the Memory passed to
updateTexture2Dfor a video decode destination texture. The renderer parses the slice / tile-group header out of the bitstream and translates it to the backend-specific decoder arguments.A single call may submit a batch of access units:
bitstreamis the back-to-back concatenation ofnumAusaccess units, andaus[ii]holds the size and PTS of each. AUs are enqueued in array order (which is the codec’s decode order). SetnumAus == 0(andbitstream == NULL) for a presentation-only tick that only advances the playback clock.The
bitstreamandauspointers must remain valid until bgfx has consumed the submission (bgfx::copyonly deep-copies theVideoDecoderFramestruct itself, not the buffers it references).- Attention
C99’s equivalent binding is
bgfx_video_decoder_frame_t.
Public Members
-
uint32_t magic
Structure magic. Must be ‘BX_MAKEFOURCC(‘V’, ‘D’, ‘F’, 0x0)`.
-
const uint8_t *bitstream
Concatenated access-unit bitstream (decode order). NULL for presentation-only ticks.
-
const VideoDecoderAu *aus
Per-AU size and PTS array. NULL when
numAus == 0.
-
uint32_t numAus
Number of access units in this batch. 0 for presentation-only ticks.
-
int64_t presentationTimeUs
Current playback wall-clock time. Driver dispatches the picture whose
ptsUsbest matches. Must be monotonically non-decreasing between non-SETcalls.
-
uint8_t flags
Per-frame submission flags. See:
BGFX_VIDEO_DECODE_FRAME_*.
-
bool bgfx::isTextureValid(uint16_t _depth, bool _cubeMap, uint16_t _numLayers, TextureFormat::Enum _format, uint64_t _flags)
Validate texture parameters.
- Attention
C99’s equivalent binding is
bgfx_is_texture_valid.
- Parameters:
_depth – [in] Depth dimension of volume texture.
_cubeMap – [in] Indicates that texture contains cubemap.
_numLayers – [in] Number of layers in texture array.
_format – [in] Texture format. See:
TextureFormat::Enum._flags – [in] Texture flags. See
BGFX_TEXTURE_*.
- Returns:
True if a texture with the same parameters can be created.
-
bool bgfx::isVideoCodecValid(VideoCodec::Enum _codec, uint8_t _chroma, uint8_t _bitDepth, uint16_t _codedWidth, uint16_t _codedHeight, uint8_t _maxDpbSlots, uint8_t _maxActiveReferences)
Validate video codec parameters. Use to check whether the requested combination of codec / bit depth / chroma / dimensions / DPB layout can be hardware decoded on the current device. Coarse capability discovery is
Caps::supported & BGFX_CAPS_VIDEO_DECODEandCaps::codecs[].- Attention
C99’s equivalent binding is
bgfx_is_video_codec_valid.
- Parameters:
_codec – [in] Video codec. See:
VideoCodec::Enum._chroma – [in] Chroma subsampling. 0 = 4:2:0, 2 = 4:2:2, 4 = 4:4:4.
_bitDepth – [in] Bit depth per component. 8, 10 or 12.
_codedWidth – [in] Coded picture width (macroblock / CTU / superblock aligned).
_codedHeight – [in] Coded picture height.
_maxDpbSlots – [in] Maximum decoded picture buffer slot count.
_maxActiveReferences – [in] Maximum number of reference frames active at once.
- Returns:
True if a video decoder with the same parameters can be created.
-
void bgfx::calcTextureSize(TextureInfo &_info, uint16_t _width, uint16_t _height, uint16_t _depth, bool _cubeMap, bool _hasMips, uint16_t _numLayers, TextureFormat::Enum _format)
Calculate amount of memory required for texture.
- Attention
C99’s equivalent binding is
bgfx_calc_texture_size.
- Parameters:
_info – [out] Resulting texture info structure. See:
TextureInfo._width – [in] Width.
_height – [in] Height.
_depth – [in] Depth dimension of volume texture.
_cubeMap – [in] Indicates that texture contains cubemap.
_hasMips – [in] Indicates that texture contains full mip-map chain.
_numLayers – [in] Number of layers in texture array.
_format – [in] Texture format. See:
TextureFormat::Enum.
-
TextureHandle bgfx::createTexture(const Memory *_mem, uint64_t _flags = BGFX_TEXTURE_NONE | BGFX_SAMPLER_NONE, uint8_t _skip = 0, TextureInfo *_info = NULL)
Create texture from memory buffer.
- Attention
C99’s equivalent binding is
bgfx_create_texture.
- Parameters:
_mem – [in] DDS, KTX or PVR texture binary data.
_flags – [in] Texture creation (see
BGFX_TEXTURE_*.), and sampler (seeBGFX_SAMPLER_*) flags. Default texture sampling mode is linear, and wrap mode is repeat.BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP]- Mirror or clamp to edge wrap mode.BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]- Point or anisotropic sampling.
_skip – [in] Skip top level mips when parsing texture.
_info – [out] When non-
NULLis specified it returns parsed texture information.
- Returns:
Texture handle.
-
TextureHandle bgfx::createTexture2D(uint16_t _width, uint16_t _height, bool _hasMips, uint16_t _numLayers, TextureFormat::Enum _format, uint64_t _flags = BGFX_TEXTURE_NONE | BGFX_SAMPLER_NONE, const Memory *_mem = NULL, uint64_t _external = 0)
Create 2D texture.
- Attention
C99’s equivalent binding is
bgfx_create_texture_2d.
- Parameters:
_width – [in] Width.
_height – [in] Height.
_hasMips – [in] Indicates that texture contains full mip-map chain. Ignored when
BGFX_TEXTURE_MIP_COUNTis set in _flags._numLayers – [in] Number of layers in texture array.
_format – [in] Texture format. See:
TextureFormat::Enum._flags – [in] Texture creation (see
BGFX_TEXTURE_*.), and sampler (seeBGFX_SAMPLER_*) flags. Default texture sampling mode is linear, and wrap mode is repeat.BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP]- Mirror or clamp to edge wrap mode.BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]- Point or anisotropic sampling.
_mem – [in] Texture data. If
_memis non-NULL, created texture will be immutable. If_memis NULL content of the texture is uninitialized. When_numLayersis more than 1, expected memory layout is texture and all mips together for each array element._external – [in] Native API pointer to texture.
- Returns:
Texture handle.
-
TextureHandle bgfx::createTexture2D(BackbufferRatio::Enum _ratio, bool _hasMips, uint16_t _numLayers, TextureFormat::Enum _format, uint64_t _flags = BGFX_TEXTURE_NONE | BGFX_SAMPLER_NONE)
Create texture with size based on back-buffer ratio. Texture will maintain ratio if back buffer resolution changes.
- Attention
C99’s equivalent binding is
bgfx_create_texture_2d_scaled.
- Parameters:
_ratio – [in] Texture size in respect to back-buffer size. See:
BackbufferRatio::Enum._hasMips – [in] Indicates that texture contains full mip-map chain. Ignored when
BGFX_TEXTURE_MIP_COUNTis set in _flags._numLayers – [in] Number of layers in texture array.
_format – [in] Texture format. See:
TextureFormat::Enum._flags – [in] Texture creation (see
BGFX_TEXTURE_*.), and sampler (seeBGFX_SAMPLER_*) flags. Default texture sampling mode is linear, and wrap mode is repeat.BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP]- Mirror or clamp to edge wrap mode.BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]- Point or anisotropic sampling.
- Returns:
Texture handle.
-
TextureHandle bgfx::createTexture3D(uint16_t _width, uint16_t _height, uint16_t _depth, bool _hasMips, TextureFormat::Enum _format, uint64_t _flags = BGFX_TEXTURE_NONE | BGFX_SAMPLER_NONE, const Memory *_mem = NULL, uint64_t _external = 0)
Create 3D texture.
- Attention
C99’s equivalent binding is
bgfx_create_texture_3d.
- Parameters:
_width – [in] Width.
_height – [in] Height.
_depth – [in] Depth.
_hasMips – [in] Indicates that texture contains full mip-map chain. Ignored when
BGFX_TEXTURE_MIP_COUNTis set in _flags._format – [in] Texture format. See:
TextureFormat::Enum._flags – [in] Texture creation (see
BGFX_TEXTURE_*.), and sampler (seeBGFX_SAMPLER_*) flags. Default texture sampling mode is linear, and wrap mode is repeat.BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP]- Mirror or clamp to edge wrap mode.BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]- Point or anisotropic sampling.
_mem – [in] Texture data. If
_memis non-NULL, created texture will be immutable. If_memis NULL content of the texture is uninitialized. When_numLayersis more than 1, expected memory layout is texture and all mips together for each array element._external – [in] Native API pointer to texture.
- Returns:
Texture handle.
-
TextureHandle bgfx::createTextureCube(uint16_t _size, bool _hasMips, uint16_t _numLayers, TextureFormat::Enum _format, uint64_t _flags = BGFX_TEXTURE_NONE | BGFX_SAMPLER_NONE, const Memory *_mem = NULL, uint64_t _external = 0)
Create Cube texture.
- Attention
C99’s equivalent binding is
bgfx_create_texture_cube.
- Parameters:
_size – [in] Cube side size.
_hasMips – [in] Indicates that texture contains full mip-map chain. Ignored when
BGFX_TEXTURE_MIP_COUNTis set in _flags._numLayers – [in] Number of layers in texture array.
_format – [in] Texture format. See:
TextureFormat::Enum._flags – [in] Texture creation (see
BGFX_TEXTURE_*.), and sampler (seeBGFX_SAMPLER_*) flags. Default texture sampling mode is linear, and wrap mode is repeat.BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP]- Mirror or clamp to edge wrap mode.BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]- Point or anisotropic sampling.
_mem – [in] Texture data. If
_memis non-NULL, created texture will be immutable. If_memis NULL content of the texture is uninitialized. When_numLayersis more than_external – [in] Native API pointer to texture.
- Returns:
Texture handle.
-
void bgfx::updateTexture2D(TextureHandle _handle, uint16_t _layer, uint8_t _mip, uint16_t _x, uint16_t _y, uint16_t _width, uint16_t _height, const Memory *_mem, uint16_t _pitch = UINT16_MAX)
Update 2D texture.
- Attention
It’s valid to update only mutable texture. See
bgfx::createTexture2Dfor more info.- Attention
C99’s equivalent binding is
bgfx_update_texture_2d.
- Parameters:
_handle – [in] Texture handle.
_layer – [in] Layer in texture array.
_mip – [in] Mip level.
_x – [in] X offset in texture.
_y – [in] Y offset in texture.
_width – [in] Width of texture block.
_height – [in] Height of texture block.
_mem – [in] Texture update data.
_pitch – [in] Pitch of input image (bytes). When _pitch is set to UINT16_MAX, it will be calculated internally based on _width.
-
void bgfx::updateTexture3D(TextureHandle _handle, uint8_t _mip, uint16_t _x, uint16_t _y, uint16_t _z, uint16_t _width, uint16_t _height, uint16_t _depth, const Memory *_mem)
Update 3D texture.
- Attention
It’s valid to update only mutable texture. See
bgfx::createTexture3Dfor more info.- Attention
C99’s equivalent binding is
bgfx_update_texture_3d.
- Parameters:
_handle – [in] Texture handle.
_mip – [in] Mip level.
_x – [in] X offset in texture.
_y – [in] Y offset in texture.
_z – [in] Z offset in texture.
_width – [in] Width of texture block.
_height – [in] Height of texture block.
_depth – [in] Depth of texture block.
_mem – [in] Texture update data.
-
void bgfx::updateTextureCube(TextureHandle _handle, uint16_t _layer, uint8_t _side, uint8_t _mip, uint16_t _x, uint16_t _y, uint16_t _width, uint16_t _height, const Memory *_mem, uint16_t _pitch = UINT16_MAX)
Update Cube texture.
- Attention
It’s valid to update only mutable texture. See
bgfx::createTextureCubefor more info.- Attention
C99’s equivalent binding is
bgfx_update_texture_cube.
- Parameters:
_handle – [in] Texture handle.
_layer – [in] Layer in texture array.
_side – [in] Cubemap side
BGFX_CUBE_MAP_<POSITIVE or NEGATIVE>_<X, Y or Z>, where 0 is +X, 1 is -X, 2 is +Y, 3 is -Y, 4 is +Z, and 5 is -Z. +——-—+ |-z 2| | ^ +y | | | | Unfolded cube: | +-—>+x | +——-—+——-—+——-—+——-—+ |+y 1|+y 4|+y 0|+y 5| | ^ -x | ^ +z | ^ +x | ^ -z | | | | | | | | | | | +-—>+z | +-—>+x | +-—>-z | +-—>-x | +——-—+——-—+——-—+——-—+ |+z 3| | ^ -y | | | | | +-—>+x | +——-—+_mip – [in] Mip level.
_x – [in] X offset in texture.
_y – [in] Y offset in texture.
_width – [in] Width of texture block.
_height – [in] Height of texture block.
_mem – [in] Texture update data.
_pitch – [in] Pitch of input image (bytes). When _pitch is set to UINT16_MAX, it will be calculated internally based on _width.
-
void bgfx::clear(TextureHandle _handle, uint8_t _mip = 0, uint8_t _numMips = UINT8_MAX, uint16_t _layer = 0, uint16_t _numLayers = UINT16_MAX)
Clear a texture subresource range to zero.
- Attention
C99’s equivalent binding is
bgfx_clear_texture.
- Parameters:
_handle – [in] Texture handle.
_mip – [in] First mip level.
_numMips – [in] Number of mip levels.
_layer – [in] First array layer (or 3D depth slice base).
_numLayers – [in] Number of layers.
-
uint32_t bgfx::read(const TextureRegion &_src, void *_data)
Read back texture content.
Read back is not intended to be used in the main render loop, since it stalls the GPU.
Remark
Read back is asynchronous, and the result is available at the returned frame.
TextureRegion::zselects cube face, 3D slice, or array layer. The region must cover the whole mip.- Attention
Texture must be created with
BGFX_TEXTURE_READ_BACKflag. It’s a texture for CPU readback, and can’t be a GPU resource at the same time. Seeexamples/30-picking.- Attention
C99’s equivalent binding is
bgfx_read_texture.
- Parameters:
_src – [in] Source texture region.
_data – [in] Destination buffer.
- Returns:
Frame number when the result will be available. See:
bgfx::frame. If the device is lost before then,bgfx::CallbackI::fatalreportsFatal::DeviceLostin that frame, and_datais left untouched.
-
void *bgfx::getDirectAccessPtr(TextureHandle _handle)
Returns texture direct access pointer.
- Attention
Availability depends on:
BGFX_CAPS_TEXTURE_DIRECT_ACCESS. This feature is available on GPUs that have unified memory architecture (UMA) support.- Attention
C99’s equivalent binding is
bgfx_get_direct_access_ptr.
- Parameters:
_handle – [in] Texture handle.
- Returns:
Pointer to texture memory. If returned pointer is
NULLdirect access is not available for this texture. If pointer isUINTPTR_MAXsentinel value it means texture is pending creation. Pointer returned can be cached and it will be valid until texture is destroyed.
-
void bgfx::destroy(TextureHandle _handle)
Destroy texture.
- Attention
C99’s equivalent binding is
bgfx_destroy_texture.
- Parameters:
_handle – [in] Texture handle.
Frame Buffers
-
struct Attachment
Frame buffer texture attachment info.
- Attention
C99’s equivalent binding is
bgfx_attachment_t.
Public Functions
-
void init(TextureHandle _handle, Access::Enum _access = Access::Write, uint16_t _layer = 0, uint16_t _numLayers = 1, uint16_t _mip = 0, uint8_t _flags = BGFX_ATTACHMENT_AUTO_GEN_MIPS)
Init attachment.
- Attention
C99’s equivalent binding is
bgfx_attachment_init.
- Parameters:
_handle – [in] Render target texture handle.
_access – [in] Access. See
Access::Enum._layer – [in] Cubemap side or depth layer/slice to use.
_numLayers – [in] Number of texture layer/slice(s) in array to use.
_mip – [in] Mip level.
_flags – [in] Attachment flags. See:
BGFX_ATTACHMENT_*
Public Members
-
Access::Enum access
Attachment access. See
Access::Enum.
-
TextureHandle handle
Render target texture handle.
-
uint16_t mip
Mip level.
-
uint16_t layer
Cubemap side or depth layer/slice to use.
-
uint16_t numLayers
Number of texture layer/slice(s) in array to use.
-
uint8_t flags
Attachment flags. See:
BGFX_ATTACHMENT_*
-
bool bgfx::isFrameBufferValid(uint8_t _num, const Attachment *_attachment)
Validate frame buffer parameters.
- Attention
C99’s equivalent binding is
bgfx_is_frame_buffer_valid.
- Parameters:
_num – [in] Number of attachments.
_attachment – [in] Attachment texture info. See:
bgfx::Attachment.
- Returns:
True if a frame buffer with the same parameters can be created.
-
FrameBufferHandle bgfx::createFrameBuffer(uint16_t _width, uint16_t _height, TextureFormat::Enum _format, uint64_t _textureFlags = BGFX_SAMPLER_U_CLAMP | BGFX_SAMPLER_V_CLAMP)
Create frame buffer (simple).
- Attention
C99’s equivalent binding is
bgfx_create_frame_buffer.
- Parameters:
_width – [in] Texture width.
_height – [in] Texture height.
_format – [in] Texture format. See:
TextureFormat::Enum._textureFlags – [in] Texture creation (see
BGFX_TEXTURE_*.), and sampler (seeBGFX_SAMPLER_*) flags. Default texture sampling mode is linear, and wrap mode is repeat.BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP]- Mirror or clamp to edge wrap mode.BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]- Point or anisotropic sampling.
- Returns:
Frame buffer handle.
-
FrameBufferHandle bgfx::createFrameBuffer(BackbufferRatio::Enum _ratio, TextureFormat::Enum _format, uint64_t _textureFlags = BGFX_SAMPLER_U_CLAMP | BGFX_SAMPLER_V_CLAMP)
Create frame buffer with size based on back-buffer ratio. Frame buffer will maintain ratio if back buffer resolution changes.
- Attention
C99’s equivalent binding is
bgfx_create_frame_buffer_scaled.
- Parameters:
_ratio – [in] Frame buffer size in respect to back-buffer size. See:
BackbufferRatio::Enum._format – [in] Texture format. See:
TextureFormat::Enum._textureFlags – [in] Texture creation (see
BGFX_TEXTURE_*.), and sampler (seeBGFX_SAMPLER_*) flags. Default texture sampling mode is linear, and wrap mode is repeat.BGFX_SAMPLER_[U/V/W]_[MIRROR/CLAMP]- Mirror or clamp to edge wrap mode.BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]- Point or anisotropic sampling.
- Returns:
Frame buffer handle.
-
FrameBufferHandle bgfx::createFrameBuffer(uint8_t _num, const TextureHandle *_handles, bool _destroyTexture = false)
Create MRT frame buffer from texture handles (simple).
- Attention
C99’s equivalent binding is
bgfx_create_frame_buffer_from_handles.
- Parameters:
_num – [in] Number of texture handles.
_handles – [in] Texture attachments.
_destroyTexture – [in] If true, textures will be destroyed when frame buffer is destroyed.
- Returns:
Frame buffer handle.
-
FrameBufferHandle bgfx::createFrameBuffer(uint8_t _num, const Attachment *_attachment, bool _destroyTexture = false)
Create MRT frame buffer from texture handles with specific layer and mip level.
- Attention
C99’s equivalent binding is
bgfx_create_frame_buffer_from_attachment.
- Parameters:
_num – [in] Number of attachments.
_attachment – [in] Attachment texture info. See:
bgfx::Attachment._destroyTexture – [in] If true, textures will be destroyed when frame buffer is destroyed.
- Returns:
Frame buffer handle.
-
void bgfx::setName(FrameBufferHandle _handle, const char *_name, int32_t _len = INT32_MAX)
Set frame buffer debug name.
- Attention
C99’s equivalent binding is
bgfx_set_frame_buffer_name.
- Parameters:
_handle – [in] Frame buffer handle.
_name – [in] Frame buffer name.
_len – [in] Frame buffer name length (if length is INT32_MAX, it’s expected that _name is zero terminated string.
-
TextureHandle bgfx::getTexture(FrameBufferHandle _handle, uint8_t _attachment = 0)
Obtain texture handle of frame buffer attachment.
- Attention
C99’s equivalent binding is
bgfx_get_texture.
- Parameters:
_handle – [in] Frame buffer handle.
_attachment –
-
void bgfx::destroy(FrameBufferHandle _handle)
Destroy frame buffer.
- Attention
C99’s equivalent binding is
bgfx_destroy_frame_buffer.
- Parameters:
_handle – [in] Frame buffer handle.
Instance Buffer
-
uint32_t bgfx::getAvailInstanceDataBuffer(uint32_t _num, uint16_t _stride)
Returns number of requested or maximum available instance buffer slots.
- Attention
C99’s equivalent binding is
bgfx_get_avail_instance_data_buffer.
- Parameters:
_num – [in] Number of required instances.
_stride – [in] Stride per instance.
- Returns:
Number of requested or maximum available instance buffer slots.
-
void bgfx::allocInstanceDataBuffer(InstanceDataBuffer *_idb, uint32_t _num, uint16_t _stride)
Allocate instance data buffer.
- Attention
C99’s equivalent binding is
bgfx_alloc_instance_data_buffer.
- Parameters:
_idb – [out] InstanceDataBuffer structure will be filled, and will be valid for duration of frame, and can be reused for multiple draw calls.
_num – [in] Number of instances.
_stride – [in] Instance stride. Must be multiple of 16.
Indirect Buffer
-
IndirectBufferHandle bgfx::createIndirectBuffer(uint32_t _num)
Create draw indirect buffer.
- Attention
C99’s equivalent binding is
bgfx_create_indirect_buffer.
- Parameters:
_num – [in] Number of indirect calls.
- Returns:
Indirect buffer handle.
-
void bgfx::destroy(IndirectBufferHandle _handle)
Destroy draw indirect buffer.
- Attention
C99’s equivalent binding is
bgfx_destroy_indirect_buffer.
- Parameters:
_handle – [in] Indirect buffer handle.
Occlusion Query
-
struct OcclusionQueryResult
Occlusion query result.
- Attention
C99’s equivalent binding is
bgfx_occlusion_query_result_t.
-
OcclusionQueryHandle bgfx::createOcclusionQuery()
Create occlusion query. Occlusion queries allow the GPU to determine if any pixels passed the depth test.
- Attention
C99’s equivalent binding is
bgfx_create_occlusion_query.
- Returns:
Handle to occlusion query object.
-
OcclusionQueryResult::Enum bgfx::getResult(OcclusionQueryHandle _handle, int32_t *_result = NULL)
Retrieve occlusion query result from previous frame.
- Attention
C99’s equivalent binding is
bgfx_get_result.
- Parameters:
_handle – [in] Handle to occlusion query object.
_result – [out] Number of pixels that passed test. This argument can be
NULLif result of occlusion query is not needed.
- Returns:
Occlusion query result.
-
void bgfx::destroy(OcclusionQueryHandle _handle)
Destroy occlusion query.
- Attention
C99’s equivalent binding is
bgfx_destroy_occlusion_query.
- Parameters:
_handle – [in] Handle to occlusion query object.