mirrors
/
bgfx
mirror of https://github.com/bkaradzic/bgfx
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Added docs source.

This commit is contained in:
Бранимир Караџић 2022-03-31 19:22:38 -07:00
parent f86499b726
commit 6601587af0
8 changed files with 2192 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

595
docs/bgfx.rst Normal file
View File

@ -0,0 +1,595 @@
API Reference
=============
.. note::
TL;DR for simple walkthrough how to use bgfx API, see `Hello, bgfx! <https://dev.to/pperon/hello-bgfx-4dka>`__,
`bgfx-minimal-example <https://github.com/jpcy/bgfx-minimal-example#bgfx-minimal-example>`__,
or `Using the bgfx library with C++ on Ubuntu <https://www.sandeepnambiar.com/getting-started-with-bgfx/>`__
tutorial.
General
-------
Initialization and Shutdown
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. doxygenstruct:: bgfx::Init
:members:
.. doxygenstruct:: bgfx::Resolution
:members:
.. doxygenfunction:: bgfx::init
.. doxygendefine:: BGFX_PCI_ID_NONE
.. doxygendefine:: BGFX_PCI_ID_SOFTWARE_RASTERIZER
.. doxygendefine:: BGFX_PCI_ID_AMD
.. doxygendefine:: BGFX_PCI_ID_INTEL
.. doxygendefine:: BGFX_PCI_ID_NVIDIA
.. doxygenstruct:: bgfx::CallbackI
:members:
.. doxygenfunction:: bgfx::shutdown
Updating
~~~~~~~~
Reset
*****
.. doxygenfunction:: bgfx::reset
.. doxygendefine:: BGFX_RESET_NONE
.. doxygendefine:: BGFX_RESET_FULLSCREEN
.. doxygendefine:: BGFX_RESET_MSAA_X2
.. doxygendefine:: BGFX_RESET_MSAA_X4
.. doxygendefine:: BGFX_RESET_MSAA_X8
.. doxygendefine:: BGFX_RESET_MSAA_X16
.. doxygendefine:: BGFX_RESET_VSYNC
.. doxygendefine:: BGFX_RESET_MAXANISOTROPY
.. doxygendefine:: BGFX_RESET_CAPTURE
.. doxygendefine:: BGFX_RESET_FLUSH_AFTER_RENDER
.. doxygendefine:: BGFX_RESET_FLIP_AFTER_RENDER
.. doxygendefine:: BGFX_RESET_SRGB_BACKBUFFER
.. doxygendefine:: BGFX_RESET_HDR10
.. doxygendefine:: BGFX_RESET_HIDPI
.. doxygendefine:: BGFX_RESET_DEPTH_CLAMP
Frame
*****
.. doxygenfunction:: bgfx::frame
Debug
~~~~~
Debug Features
**************
.. doxygenfunction:: bgfx::setDebug
Debug Flags
***********
.. doxygendefine:: BGFX_DEBUG_NONE
.. doxygendefine:: BGFX_DEBUG_WIREFRAME
.. doxygendefine:: BGFX_DEBUG_IFH
.. doxygendefine:: BGFX_DEBUG_STATS
.. doxygendefine:: BGFX_DEBUG_TEXT
.. doxygendefine:: BGFX_DEBUG_PROFILER
Debug Text Display
******************
.. doxygenfunction:: bgfx::dbgTextClear
.. doxygenfunction:: bgfx::dbgTextPrintf
.. doxygenfunction:: bgfx::dbgTextPrintfVargs
.. doxygenfunction:: bgfx::dbgTextImage
Querying information
~~~~~~~~~~~~~~~~~~~~
Renderer
********
.. doxygenfunction:: bgfx::getSupportedRenderers
.. doxygenfunction:: bgfx::getRendererType
.. doxygenstruct:: bgfx::RendererType
:members:
Capabilities
************
.. doxygenfunction:: bgfx::getCaps
.. doxygenstruct:: bgfx::Caps
:members:
Available Caps
""""""""""""""
.. doxygendefine:: BGFX_CAPS_ALPHA_TO_COVERAGE
.. doxygendefine:: BGFX_CAPS_BLEND_INDEPENDENT
.. doxygendefine:: BGFX_CAPS_COMPUTE
.. doxygendefine:: BGFX_CAPS_CONSERVATIVE_RASTER
.. doxygendefine:: BGFX_CAPS_DRAW_INDIRECT
.. doxygendefine:: BGFX_CAPS_FRAGMENT_DEPTH
.. doxygendefine:: BGFX_CAPS_FRAGMENT_ORDERING
.. doxygendefine:: BGFX_CAPS_GRAPHICS_DEBUGGER
.. doxygendefine:: BGFX_CAPS_HDR10
.. doxygendefine:: BGFX_CAPS_HIDPI
.. doxygendefine:: BGFX_CAPS_IMAGE_RW
.. doxygendefine:: BGFX_CAPS_INDEX32
.. doxygendefine:: BGFX_CAPS_INSTANCING
.. doxygendefine:: BGFX_CAPS_OCCLUSION_QUERY
.. doxygendefine:: BGFX_CAPS_RENDERER_MULTITHREADED
.. doxygendefine:: BGFX_CAPS_SWAP_CHAIN
.. doxygendefine:: BGFX_CAPS_TEXTURE_2D_ARRAY
.. doxygendefine:: BGFX_CAPS_TEXTURE_3D
.. doxygendefine:: BGFX_CAPS_TEXTURE_BLIT
.. doxygendefine:: BGFX_CAPS_TEXTURE_COMPARE_ALL
.. doxygendefine:: BGFX_CAPS_TEXTURE_COMPARE_LEQUAL
.. doxygendefine:: BGFX_CAPS_TEXTURE_CUBE_ARRAY
.. doxygendefine:: BGFX_CAPS_TEXTURE_DIRECT_ACCESS
.. doxygendefine:: BGFX_CAPS_TEXTURE_READ_BACK
.. doxygendefine:: BGFX_CAPS_VERTEX_ATTRIB_HALF
.. doxygendefine:: BGFX_CAPS_VERTEX_ATTRIB_UINT10
.. doxygendefine:: BGFX_CAPS_VERTEX_ID
Statistics
**********
.. doxygenfunction:: bgfx::getStats
.. doxygenstruct:: bgfx::Stats
:members:
.. doxygenstruct:: bgfx::ViewStats
:members:
.. doxygenstruct:: bgfx::EncoderStats
:members:
Platform specific
~~~~~~~~~~~~~~~~~
These are platform specific APIs. It is only necessary to use these APIs in conjunction with
creating windows.
.. doxygenfunction:: bgfx::renderFrame
.. doxygenstruct:: bgfx::RenderFrame
:members:
.. doxygenfunction:: bgfx::setPlatformData
.. doxygenstruct:: bgfx::PlatformData
:members:
.. doxygenfunction:: bgfx::getInternalData
.. doxygenstruct:: bgfx::InternalData
:members:
.. doxygenfunction:: bgfx::overrideInternal(TextureHandle _handle, uintptr_t _ptr)
.. doxygenfunction:: bgfx::overrideInternal(TextureHandle _handle, uint16_t _width, uint16_t _height, uint8_t _numMips, TextureFormat::Enum _format, uint64_t _flags = BGFX_TEXTURE_NONE | BGFX_SAMPLER_NONE)
Miscellaneous
~~~~~~~~~~~~~
.. doxygenfunction:: bgfx::vertexPack
.. doxygenfunction:: bgfx::vertexUnpack
.. doxygenfunction:: bgfx::vertexConvert
.. doxygenfunction:: bgfx::weldVertices
.. doxygenstruct:: bgfx::TopologyConvert
:members:
.. doxygenfunction:: bgfx::topologyConvert
.. doxygenstruct:: bgfx::TopologySort
:members:
.. doxygenfunction:: bgfx::topologySortTriList
.. doxygenfunction:: bgfx::discard
.. doxygenfunction:: bgfx::touch
.. doxygenfunction:: bgfx::setPaletteColor(uint8_t _index, uint32_t _rgba)
.. doxygenfunction:: bgfx::setPaletteColor(uint8_t _index, const float _rgba[4])
.. doxygenfunction:: bgfx::setPaletteColor(uint8_t _index, float _r, float _g, float _b, float _a)
.. doxygenfunction:: bgfx::requestScreenShot
Views
-----
View is primary sorting mechanism in bgfx. View represent bucket of draw and compute calls. Compute
and draw calls inside bucket are sorted in the way that all compute calls are executed before draw
calls. Compute calls are always in order of submission, while draw calls are sorted by internal
state if view is not in sequential mode. In the most of cases when z-buffer is used this change in
order is not noticable to desired output. In cases where order has to be preserved (for example in
rendering GUIs), view can be set to be in sequential order. Sequential order is less efficient,
because it doesn't allow state change optimization, and should be avoided when possible.
By default views ids are sorted in ascending order. For dynamic renderers where order might not be
known until the last moment, view ids can be remaped to arbitrary order by calling
`bgfx::setViewOrder`.
View state is preserved between multiple frames.
.. doxygenfunction:: bgfx::setViewName
.. doxygenfunction:: bgfx::setViewRect(ViewId _id, uint16_t _x, uint16_t _y, uint16_t _width, uint16_t _height)
.. doxygenfunction:: bgfx::setViewRect(ViewId _id, uint16_t _x, uint16_t _y, BackbufferRatio::Enum _ratio)
.. doxygenfunction:: bgfx::setViewScissor
.. doxygenfunction:: bgfx::setViewClear(ViewId _id, uint16_t _flags, uint32_t _rgba = 0x000000ff, float _depth = 1.0f, uint8_t _stencil = 0)
.. doxygenfunction:: bgfx::setViewClear(ViewId _id, uint16_t _flags, float _depth, uint8_t _stencil, uint8_t _0 = UINT8_MAX, uint8_t _1 = UINT8_MAX, uint8_t _2 = UINT8_MAX, uint8_t _3 = UINT8_MAX, uint8_t _4 = UINT8_MAX, uint8_t _5 = UINT8_MAX, uint8_t _6 = UINT8_MAX, uint8_t _7 = UINT8_MAX)
.. doxygenstruct:: bgfx::ViewMode
:members:
.. doxygenfunction:: bgfx::setViewMode
.. doxygenfunction:: bgfx::setViewFrameBuffer
.. doxygenfunction:: bgfx::setViewTransform
.. doxygenfunction:: bgfx::setViewOrder
.. doxygenfunction:: bgfx::resetView
Encoder
-------
Encoder
~~~~~~~
API for multi-threaded submission.
.. doxygenfunction:: bgfx::begin
.. doxygenfunction:: bgfx::end
.. doxygenstruct:: bgfx::Encoder
:members:
Draw
~~~~
Draw state is not preserved between two draw calls. All state is cleared after calling
`bgfx::submit`.
State
*****
Debug
*****
.. doxygenfunction:: bgfx::setMarker
.. doxygenfunction:: bgfx::setName(ShaderHandle _handle, const char *_name, int32_t _len = INT32_MAX)
.. doxygenfunction:: bgfx::setName(TextureHandle _handle, const char *_name, int32_t _len = INT32_MAX)
State
*****
.. doxygenfunction:: bgfx::setState
State Flags
***********
**Write**
.. doxygendefine:: BGFX_STATE_WRITE_R
.. doxygendefine:: BGFX_STATE_WRITE_G
.. doxygendefine:: BGFX_STATE_WRITE_B
.. doxygendefine:: BGFX_STATE_WRITE_RGB
.. doxygendefine:: BGFX_STATE_WRITE_A
.. doxygendefine:: BGFX_STATE_WRITE_Z
**Depth Test**
.. doxygendefine:: BGFX_STATE_DEPTH_TEST_LESS
.. doxygendefine:: BGFX_STATE_DEPTH_TEST_LEQUAL
.. doxygendefine:: BGFX_STATE_DEPTH_TEST_EQUAL
.. doxygendefine:: BGFX_STATE_DEPTH_TEST_GEQUAL
.. doxygendefine:: BGFX_STATE_DEPTH_TEST_GREATER
.. doxygendefine:: BGFX_STATE_DEPTH_TEST_NOTEQUAL
.. doxygendefine:: BGFX_STATE_DEPTH_TEST_NEVER
.. doxygendefine:: BGFX_STATE_DEPTH_TEST_ALWAYS
**Blend Mode**
.. doxygendefine:: BGFX_STATE_BLEND_ZERO
.. doxygendefine:: BGFX_STATE_BLEND_ONE
.. doxygendefine:: BGFX_STATE_BLEND_SRC_COLOR
.. doxygendefine:: BGFX_STATE_BLEND_INV_SRC_COLOR
.. doxygendefine:: BGFX_STATE_BLEND_SRC_ALPHA
.. doxygendefine:: BGFX_STATE_BLEND_INV_SRC_ALPHA
.. doxygendefine:: BGFX_STATE_BLEND_DST_ALPHA
.. doxygendefine:: BGFX_STATE_BLEND_INV_DST_ALPHA
.. doxygendefine:: BGFX_STATE_BLEND_DST_COLOR
.. doxygendefine:: BGFX_STATE_BLEND_INV_DST_COLOR
.. doxygendefine:: BGFX_STATE_BLEND_SRC_ALPHA_SAT
.. doxygendefine:: BGFX_STATE_BLEND_FACTOR
.. doxygendefine:: BGFX_STATE_BLEND_INV_FACTOR
**Blend Equaation**
.. doxygendefine:: BGFX_STATE_BLEND_EQUATION_ADD
.. doxygendefine:: BGFX_STATE_BLEND_EQUATION_SUB
.. doxygendefine:: BGFX_STATE_BLEND_EQUATION_REVSUB
.. doxygendefine:: BGFX_STATE_BLEND_EQUATION_MIN
.. doxygendefine:: BGFX_STATE_BLEND_EQUATION_MAX
**Primitive Culling**
.. doxygendefine:: BGFX_STATE_CULL_CW
.. doxygendefine:: BGFX_STATE_CULL_CCW
**Primitive Type**
.. doxygendefine:: BGFX_STATE_PT_TRISTRIP
.. doxygendefine:: BGFX_STATE_PT_LINES
.. doxygendefine:: BGFX_STATE_PT_LINESTRIP
.. doxygendefine:: BGFX_STATE_PT_POINTS
**Misc**
.. doxygendefine:: BGFX_STATE_BLEND_INDEPENDENT
.. doxygendefine:: BGFX_STATE_BLEND_ALPHA_TO_COVERAGE
.. doxygendefine:: BGFX_STATE_MSAA
.. doxygendefine:: BGFX_STATE_LINEAA
Stencil
*******
.. doxygenfunction:: bgfx::setStencil
Stencil Flags
*************
.. doxygendefine:: BGFX_STENCIL_TEST_LESS
Scissor
*******
When scissor rectangle is changing per draw call inside the same view use `bgfx::setScissor`,
otherwise prefer `bgfx::setViewScissor`.
.. doxygenfunction:: bgfx::setScissor(uint16_t _x, uint16_t _y, uint16_t _width, uint16_t _height)
.. doxygenfunction:: bgfx::setScissor(uint16_t _cache = UINT16_MAX)
Transform
*********
.. doxygenfunction:: bgfx::allocTransform
.. doxygenfunction:: bgfx::setTransform(const void *_mtx, uint16_t _num = 1)
.. doxygenfunction:: bgfx::setTransform(uint32_t _cache, uint16_t _num = 1)
Conditional Rendering
*********************
.. doxygenfunction:: bgfx::setCondition
Buffers
*******
.. doxygenfunction:: bgfx::setIndexBuffer(IndexBufferHandle _handle)
.. doxygenfunction:: bgfx::setIndexBuffer(IndexBufferHandle _handle, uint32_t _firstIndex, uint32_t _numIndices)
.. doxygenfunction:: bgfx::setIndexBuffer(DynamicIndexBufferHandle _handle)
.. doxygenfunction:: bgfx::setIndexBuffer(DynamicIndexBufferHandle _handle, uint32_t _firstIndex, uint32_t _numIndices)
.. doxygenstruct:: bgfx::TransientIndexBuffer
:members:
.. doxygenfunction:: bgfx::setIndexBuffer(const TransientIndexBuffer *_tib)
.. doxygenfunction:: bgfx::setIndexBuffer(const TransientIndexBuffer *_tib, uint32_t _firstIndex, uint32_t _numIndices)
.. doxygenfunction:: bgfx::setVertexBuffer(uint8_t _stream, VertexBufferHandle _handle)
.. doxygenfunction:: bgfx::setVertexBuffer(uint8_t _stream, VertexBufferHandle _handle, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)
.. doxygenfunction:: bgfx::setVertexBuffer(uint8_t _stream, DynamicVertexBufferHandle _handle)
.. doxygenfunction:: bgfx::setVertexBuffer(uint8_t _stream, DynamicVertexBufferHandle _handle, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)
.. doxygenstruct:: bgfx::TransientVertexBuffer
:members:
.. doxygenfunction:: bgfx::setVertexBuffer(uint8_t _stream, const TransientVertexBuffer *_tvb)
.. doxygenfunction:: bgfx::setVertexBuffer(uint8_t _stream, const TransientVertexBuffer *_tvb, uint32_t _startVertex, uint32_t _numVertices, VertexLayoutHandle _layoutHandle = BGFX_INVALID_HANDLE)
.. doxygenfunction:: bgfx::setVertexCount
.. doxygenstruct:: bgfx::InstanceDataBuffer
:members:
.. doxygenfunction:: bgfx::setInstanceDataBuffer(const InstanceDataBuffer *_idb)
.. doxygenfunction:: bgfx::setInstanceDataBuffer(const InstanceDataBuffer *_idb, uint32_t _start, uint32_t _num)
.. doxygenfunction:: bgfx::setInstanceDataBuffer(VertexBufferHandle _handle, uint32_t _start, uint32_t _num)
.. doxygenfunction:: bgfx::setInstanceDataBuffer(DynamicVertexBufferHandle _handle, uint32_t _start, uint32_t _num)
.. doxygenfunction:: bgfx::setInstanceCount
Textures
********
.. doxygenfunction:: bgfx::setTexture(uint8_t, UniformHandle, TextureHandle, uint32_t)
Submit
******
Within view all draw commands are executed after blit and compute commands.
.. doxygenfunction:: bgfx::submit(ViewId _id, ProgramHandle _program, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)
.. doxygenfunction:: bgfx::submit(ViewId _id, ProgramHandle _program, OcclusionQueryHandle _occlusionQuery, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)
.. doxygenfunction:: bgfx::submit(ViewId _id, ProgramHandle _program, IndirectBufferHandle _indirectHandle, uint16_t _start = 0, uint16_t _num = 1, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL)
Compute
~~~~~~~
Compute state is not preserved between two compute dispatches. All state is cleared after calling
`bgfx::dispatch`.
Buffers
*******
.. doxygenstruct:: bgfx::Access
:members:
.. doxygenfunction:: bgfx::setBuffer(uint8_t _stage, IndexBufferHandle _handle, Access::Enum _access)
.. doxygenfunction:: bgfx::setBuffer(uint8_t _stage, VertexBufferHandle _handle, Access::Enum _access)
.. doxygenfunction:: bgfx::setBuffer(uint8_t _stage, DynamicIndexBufferHandle _handle, Access::Enum _access)
.. doxygenfunction:: bgfx::setBuffer(uint8_t _stage, DynamicVertexBufferHandle _handle, Access::Enum _access)
.. doxygenfunction:: bgfx::setBuffer(uint8_t _stage, IndirectBufferHandle _handle, Access::Enum _access)
Images
******
.. doxygenfunction:: bgfx::setImage(uint8_t, TextureHandle, uint8_t, Access::Enum, TextureFormat::Enum)
Dispatch
********
Within view all compute commands are dispatched after blit commands, and before draw commands.
.. doxygenfunction:: bgfx::dispatch(ViewId _id, ProgramHandle _handle, uint32_t _numX = 1, uint32_t _numY = 1, uint32_t _numZ = 1, uint8_t _flags = BGFX_DISCARD_ALL)
.. doxygenfunction:: bgfx::dispatch(ViewId _id, ProgramHandle _handle, IndirectBufferHandle _indirectHandle, uint16_t _start = 0, uint16_t _num = 1, uint8_t _flags = BGFX_DISCARD_ALL)
Blit
~~~~
Within view all blit commands are executed before compute, and draw commands.
.. doxygenfunction:: bgfx::blit(ViewId _id, TextureHandle _dst, uint16_t _dstX, uint16_t _dstY, TextureHandle _src, uint16_t _srcX = 0, uint16_t _srcY = 0, uint16_t _width = UINT16_MAX, uint16_t _height = UINT16_MAX)
.. doxygenfunction:: bgfx::blit(ViewId _id, TextureHandle _dst, uint8_t _dstMip, uint16_t _dstX, uint16_t _dstY, uint16_t _dstZ, TextureHandle _src, uint8_t _srcMip = 0, uint16_t _srcX = 0, uint16_t _srcY = 0, uint16_t _srcZ = 0, uint16_t _width = UINT16_MAX, uint16_t _height = UINT16_MAX, uint16_t _depth = UINT16_MAX)
Resources
---------
.. doxygenstruct:: bgfx::Memory
:members:
.. doxygenfunction:: bgfx::alloc
.. doxygenfunction:: bgfx::copy
.. doxygenfunction:: bgfx::makeRef
Shaders and Programs
~~~~~~~~~~~~~~~~~~~~
.. doxygenfunction:: bgfx::createShader
.. doxygenfunction:: bgfx::getShaderUniforms
.. doxygenfunction:: bgfx::destroy(ShaderHandle _handle)
.. doxygenfunction:: bgfx::createProgram(ShaderHandle _vsh, ShaderHandle _fsh, bool _destroyShaders = false)
.. doxygenfunction:: bgfx::createProgram(ShaderHandle _csh, bool _destroyShader = false)
.. doxygenfunction:: bgfx::destroy(ProgramHandle _handle)
Uniforms
~~~~~~~~
.. doxygenfunction:: bgfx::createUniform
.. doxygenfunction:: bgfx::getUniformInfo
.. doxygenfunction:: bgfx::destroy(UniformHandle _handle)
.. doxygenstruct:: bgfx::UniformType
:members:
.. doxygenstruct:: bgfx::UniformInfo
:members:
Vertex Buffers
~~~~~~~~~~~~~~
.. doxygenfunction:: bgfx::createVertexLayout
.. doxygenfunction:: bgfx::destroy(VertexLayoutHandle _handle)
.. doxygenfunction:: bgfx::createVertexBuffer
.. doxygenfunction:: bgfx::setName(VertexBufferHandle _handle, const char *_name, int32_t _len = INT32_MAX)
.. doxygenfunction:: bgfx::destroy(VertexBufferHandle _handle)
.. doxygenstruct:: bgfx::VertexLayout
:members:
.. doxygenstruct:: bgfx::Attrib
:members:
.. doxygenstruct:: bgfx::AttribType
:members:
.. doxygenfunction:: bgfx::createDynamicVertexBuffer(uint32_t _num, const VertexLayout &_layout, uint16_t _flags = BGFX_BUFFER_NONE)
.. doxygenfunction:: bgfx::createDynamicVertexBuffer(const Memory *_mem, const VertexLayout &_layout, uint16_t _flags = BGFX_BUFFER_NONE)
.. doxygenfunction:: bgfx::update(DynamicVertexBufferHandle _handle, uint32_t _startVertex, const Memory *_mem)
.. doxygenfunction:: bgfx::destroy(DynamicVertexBufferHandle _handle)
.. doxygenfunction:: bgfx::getAvailTransientVertexBuffer
.. doxygenfunction:: bgfx::allocTransientVertexBuffer
Index Buffers
~~~~~~~~~~~~~
.. doxygenfunction:: bgfx::createIndexBuffer
.. doxygenfunction:: bgfx::setName(IndexBufferHandle _handle, const char *_name, int32_t _len = INT32_MAX)
.. doxygenfunction:: bgfx::destroy(IndexBufferHandle _handle)
.. doxygenfunction:: bgfx::createDynamicIndexBuffer(uint32_t _num, uint16_t _flags = BGFX_BUFFER_NONE)
.. doxygenfunction:: bgfx::createDynamicIndexBuffer(const Memory *_mem, uint16_t _flags = BGFX_BUFFER_NONE)
.. doxygenfunction:: bgfx::update(DynamicIndexBufferHandle _handle, uint32_t _startIndex, const Memory *_mem)
.. doxygenfunction:: bgfx::destroy(DynamicIndexBufferHandle _handle)
.. doxygenfunction:: bgfx::getAvailTransientIndexBuffer
.. doxygenfunction:: bgfx::allocTransientIndexBuffer
Textures
~~~~~~~~
.. doxygenstruct:: bgfx::TextureFormat
:members:
.. doxygenfunction:: bgfx::isTextureValid
.. doxygenstruct:: bgfx::TextureInfo
:members:
.. doxygenfunction:: bgfx::calcTextureSize
.. doxygenfunction:: bgfx::createTexture
.. doxygenfunction:: 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)
.. doxygenfunction:: bgfx::createTexture2D(BackbufferRatio::Enum _ratio, bool _hasMips, uint16_t _numLayers, TextureFormat::Enum _format, uint64_t _flags = BGFX_TEXTURE_NONE | BGFX_SAMPLER_NONE)
.. doxygenfunction:: bgfx::updateTexture2D
.. doxygenfunction:: bgfx::createTexture3D
.. doxygenfunction:: bgfx::updateTexture3D
.. doxygenfunction:: bgfx::createTextureCube
.. doxygenfunction:: bgfx::updateTextureCube
.. doxygenfunction:: bgfx::readTexture(TextureHandle, void *, uint8_t)
.. doxygenfunction:: bgfx::getDirectAccessPtr
.. doxygenfunction:: bgfx::destroy(TextureHandle _handle)
Frame Buffers
~~~~~~~~~~~~~
.. doxygenfunction:: bgfx::createFrameBuffer(uint16_t _width, uint16_t _height, TextureFormat::Enum _format, uint64_t _textureFlags = BGFX_SAMPLER_U_CLAMP | BGFX_SAMPLER_V_CLAMP)
.. doxygenfunction:: bgfx::createFrameBuffer(BackbufferRatio::Enum _ratio, TextureFormat::Enum _format, uint64_t _textureFlags = BGFX_SAMPLER_U_CLAMP | BGFX_SAMPLER_V_CLAMP)
.. doxygenfunction:: bgfx::createFrameBuffer(uint8_t _num, const TextureHandle *_handles, bool _destroyTextures = false)
.. doxygenfunction:: bgfx::createFrameBuffer(void *_nwh, uint16_t _width, uint16_t _height, TextureFormat::Enum _format = TextureFormat::Count, TextureFormat::Enum _depthFormat = TextureFormat::Count)
.. doxygenstruct:: bgfx::Attachment
:members:
.. doxygenfunction:: bgfx::createFrameBuffer(uint8_t _num, const Attachment *_attachment, bool _destroyTextures = false)
.. doxygenfunction:: bgfx::getTexture
.. doxygenfunction:: bgfx::setName(FrameBufferHandle _handle, const char *_name, int32_t _len = INT32_MAX)
.. doxygenfunction:: bgfx::destroy(FrameBufferHandle _handle)
Instance Buffer
~~~~~~~~~~~~~~~
.. doxygenfunction:: bgfx::getAvailInstanceDataBuffer
.. doxygenfunction:: bgfx::allocInstanceDataBuffer
Indirect Buffer
~~~~~~~~~~~~~~~
.. doxygenfunction:: bgfx::createIndirectBuffer
.. doxygenfunction:: bgfx::destroy(IndirectBufferHandle _handle)
Occlusion Query
~~~~~~~~~~~~~~~
.. doxygenfunction:: bgfx::createOcclusionQuery
.. doxygenstruct:: bgfx::OcclusionQueryResult
:members:
.. doxygenfunction:: bgfx::getResult
.. doxygenfunction:: bgfx::destroy(OcclusionQueryHandle _handle)

220
docs/build.rst Normal file
View File

@ -0,0 +1,220 @@
Building
========
Dependencies
------------
https://github.com/bkaradzic/bx
https://github.com/bkaradzic/bimg
Getting Source
--------------
::
git clone git://github.com/bkaradzic/bx.git
git clone git://github.com/bkaradzic/bimg.git
git clone git://github.com/bkaradzic/bgfx.git
Quick Start
-----------
These are step for users who use Windows with Visual Studio.
Enter bgfx directory:
::
cd bgfx
Generate Visual Studio 2017 project files:
::
..\bx\tools\bin\windows\genie --with-examples vs2017
Open bgfx solution in Visual Studio 2017:
::
start .build\projects\vs2017\bgfx.sln
.. note:: For more detailed prerequisites and build steps on other platforms see below.
Prerequisites
-------------
Android
~~~~~~~
Download AndroidNDK:
- https://developer.android.com/tools/sdk/ndk/index.html
Set following enironment variables:
::
setx ANDROID_NDK_ROOT <path to AndroidNDK directory>
setx ANDROID_NDK_ARM <path to AndroidNDK directory>\toolchains\arm-linux-androideabi-4.7\prebuilt\windows-x86_64
setx ANDROID_NDK_MIPS <path to AndroidNDK directory>\toolchains\mipsel-linux-android-4.7\prebuilt\windows-x86_64
setx ANDROID_NDK_X86 <path to AndroidNDK directory>\toolchains\x86-4.7\prebuilt\windows-x86_64
To deploy on Android you can use bgfx android activity:
- https://github.com/Nodrev/bgfx-android-activity#bgfx-android-activity---android-glue-for-bgfx
Linux
~~~~~
::
sudo apt-get install libgl1-mesa-dev x11proto-core-dev libx11-dev
Windows
~~~~~~~
Windows users download GnuWin32 utilities:
- http://gnuwin32.sourceforge.net/packages/make.htm
- http://gnuwin32.sourceforge.net/packages/coreutils.htm
- http://gnuwin32.sourceforge.net/packages/libiconv.htm
- http://gnuwin32.sourceforge.net/packages/libintl.htm
Build
-----
bgfx uses `GENie - Project generator tool <https://github.com/bkaradzic/genie#genie---project-generator-tool>`__
to generate project files for various platform. Binaries for Linux, OSX, and Windows are included in
bx repository.
General
~~~~~~~
::
cd bgfx
make
After calling ``make``, .build/projects/\* directory will be generated.
All intermediate files generated by compiler will be inside .build
directory structure. Deleting .build directory at any time is safe.
::
make <configuration>
Configuration is ``<platform>-<debug/release>[32/64]``. For example:
::
linux-release32, nacl-debug64, nacl-arm-debug, pnacl-release,
android-release, etc.
Windows
~~~~~~~
Visual Studio 2017 command line:
::
make vs2017-release64
Visual Studio 2017 IDE:
::
start .build/projects/vs2017/bgfx.sln
Xcode
~~~~~
Xcode command line:
::
make osx-release
cd examples/runtime
../../.build/osx64_clang/bin/examples.app/Contents/MacOS/examplesRelease
Xcode IDE:
::
../bx/tools/bin/darwin/genie --with-combined-examples --xcode=osx xcode9
open .build/projects/xcode9-osx/bgfx.xcworkspace
Due to `inability <https://github.com/bkaradzic/genie/blob/master/docs/scripting-reference.md#debugdirpath>`__
to set working directory for an Xcode project from `GENie <https://github.com/bkaradzic/genie#genie---project-generator-tool>`__
configuration file, it has to be set manually for each example project:
1. Open *"Edit scheme..."* dialog for a given project.
2. Select *"Run"* settings.
3. Check *"Use custom working directory"* and enter following path:
``${PROJECT_DIR}/../../../examples/runtime``.
Linux
~~~~~
::
make linux-release64
WinRT / UWP
~~~~~~~~~~~
::
..\bx\tools\bin\windows\genie --vs=winstore100 vs2017
Build the resulting solution and deploy to device.
.. note:: Shaders will need to be compiled with the appropriate target profile for your platform.
Amalgamated Build
-----------------
For ease of integration to other build system bgfx library can be built
with single .cpp file. It's only necessary to build
`src/amalgamated.cpp <https://github.com/bkaradzic/bgfx/blob/master/src/amalgamated.cpp>`__
(for OSX/iOS use
`src/amalgamated.mm <https://github.com/bkaradzic/bgfx/blob/master/src/amalgamated.mm>`__
instead) inside different build system.
Tools
-----
To build bgfx project files for tools, use ``--with-tools`` option:
::
..\bx\tools\bin\windows\genie --with-tools vs2017
Alternative build systems
-------------------------
**CMake**
- https://github.com/bkaradzic/bgfx.cmake
- https://github.com/JoshuaBrookover/bgfx.cmake#bgfxcmake
- https://github.com/pr0g/sdl-bgfx-imgui-starter#sdl-bgfx-imgui-starter
- https://github.com/yuki-koyama/hello-bgfx
- https://github.com/ataulien/bgfx-cmake
**fips** is a highlevel build system wrapper written in Python for C/C++ projects.
https://github.com/floooh/fips#fips
**Conan** package
https://github.com/firefalcom/bgfx-conan
Minimal example without bgfx' example harness
---------------------------------------------
This project demonstrates minimal amount of code needed to integrate bgfx with GLFW, but without
any of existing bgfx example harness. It also demonstrates how to build bgfx with alternative build
system.
https://github.com/jpcy/bgfx-minimal-example

667
docs/examples.rst Normal file
View File

@ -0,0 +1,667 @@
Examples
========
Most of the examples require shader/texture/mesh data to be loaded. When
running examples your current directory should be examples/runtime.
::
<bgfx_path>/examples/runtime $ ../../.build/<config>/bin/example-00-helloworldDebug
`00-helloworld <https://github.com/bkaradzic/bgfx/blob/master/examples/00-helloworld>`__
----------------------------------------------------------------------------------------
Initialization and debug text.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/00-helloworld/screenshot.png
:alt: example-00-helloworld
`01-cubes <https://github.com/bkaradzic/bgfx/blob/master/examples/01-cubes/cubes.cpp>`__
----------------------------------------------------------------------------------------
Rendering simple static mesh.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/01-cubes/screenshot.png
:alt: example-01-cubes
`02-metaballs <https://github.com/bkaradzic/bgfx/blob/master/examples/02-metaballs>`__
--------------------------------------------------------------------------------------
Rendering with transient buffers and embedding shaders.
.. raw:: html
<div class="emscripten">
<progress value="0" max="100" id="progress" hidden=1></progress>
</div>
<div class="spinner" id='spinner'></div>
<div class="emscripten" id="status">Downloading...</div>
<div class="emscripten_border">
<canvas class="emscripten" id="canvas" oncontextmenu="event.preventDefault()"></canvas>
</div>
<script type='text/javascript'>
var statusElement = document.getElementById('status');
var progressElement = document.getElementById('progress');
var spinnerElement = document.getElementById('spinner');
var Module = {
preRun: [],
postRun: [],
print: (function() {
var element = document.getElementById('output');
if (element) element.value = ''; // clear browser cache
return function(text) {
if (arguments.length > 1) text = Array.prototype.slice.call(arguments).join(' ');
// These replacements are necessary if you render to raw HTML
//text = text.replace(/&/g, "&amp;");
//text = text.replace(/</g, "&lt;");
//text = text.replace(/>/g, "&gt;");
//text = text.replace('\n', '<br>', 'g');
console.log(text);
if (element) {
element.value += text + "\n";
element.scrollTop = element.scrollHeight; // focus on bottom
}
};
})(),
printErr: function(text) {
if (arguments.length > 1) text = Array.prototype.slice.call(arguments).join(' ');
if (0) { // XXX disabled for safety typeof dump == 'function') {
dump(text + '\n'); // fast, straight to the real console
} else {
console.error(text);
}
},
canvas: (function() {
var canvas = document.getElementById('canvas');
// As a default initial behavior, pop up an alert when webgl context is lost. To make your
// application robust, you may want to override this behavior before shipping!
// See http://www.khronos.org/registry/webgl/specs/latest/1.0/#5.15.2
canvas.addEventListener("webglcontextlost", function(e) { alert('WebGL context lost. You will need to reload the page.'); e.preventDefault(); }, false);
return canvas;
})(),
setStatus: function(text) {
if (!Module.setStatus.last) Module.setStatus.last = { time: Date.now(), text: '' };
if (text === Module.setStatus.text) return;
var m = text.match(/([^(]+)\((\d+(\.\d+)?)\/(\d+)\)/);
var now = Date.now();
if (m && now - Date.now() < 30) return; // if this is a progress update, skip it if too soon
if (m) {
text = m[1];
progressElement.value = parseInt(m[2])*100;
progressElement.max = parseInt(m[4])*100;
progressElement.hidden = false;
spinnerElement.hidden = false;
} else {
progressElement.value = null;
progressElement.max = null;
progressElement.hidden = true;
if (!text) spinnerElement.style.display = 'none';
}
statusElement.innerHTML = text;
},
totalDependencies: 0,
monitorRunDependencies: function(left) {
this.totalDependencies = Math.max(this.totalDependencies, left);
Module.setStatus(left ? 'Preparing... (' + (this.totalDependencies-left) + '/' + this.totalDependencies + ')' : 'All downloads complete.');
}
};
Module.setStatus('Downloading...');
window.onerror = function(event) {
// TODO: do not warn on ok events like simulating an infinite loop or exitStatus
Module.setStatus('Exception thrown, see JavaScript console');
spinnerElement.style.display = 'none';
Module.setStatus = function(text) {
if (text) Module.printErr('[post-exception status] ' + text);
};
};
</script>
<script async type="text/javascript" src="example-02-metaballsRelease.bc.js"></script>
`03-raymarch <https://github.com/bkaradzic/bgfx/blob/master/examples/03-raymarch>`__
------------------------------------------------------------------------------------
Updating shader uniforms.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/03-raymarch/screenshot.png
:alt: example-03-raymarch
`04-mesh <https://github.com/bkaradzic/bgfx/blob/master/examples/04-mesh>`__
----------------------------------------------------------------------------
Loading meshes.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/04-mesh/screenshot.png
:alt: example-04-mesh
`05-instancing <https://github.com/bkaradzic/bgfx/blob/master/examples/05-instancing>`__
----------------------------------------------------------------------------------------
Geometry instancing.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/05-instancing/screenshot.png
:alt: example-05-instancing
`06-bump <https://github.com/bkaradzic/bgfx/blob/master/examples/06-bump>`__
----------------------------------------------------------------------------
Loading textures.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/06-bump/screenshot.png
:alt: example-06-bump
`07-callback <https://github.com/bkaradzic/bgfx/blob/master/examples/07-callback>`__
------------------------------------------------------------------------------------
Implementing application specific callbacks for taking screen shots,
caching OpenGL binary shaders, and video capture.
`08-update <https://github.com/bkaradzic/bgfx/blob/master/examples/08-update>`__
--------------------------------------------------------------------------------
Updating textures.
`09-hdr <https://github.com/bkaradzic/bgfx/tree/master/examples/09-hdr>`__
--------------------------------------------------------------------------
Using multiple views with frame buffers, and view order remapping.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/09-hdr/screenshot.png
:alt: example-09-hdr
`10-font <https://github.com/bkaradzic/bgfx/tree/master/examples/10-font>`__
----------------------------------------------------------------------------
Use the font system to display text and styled text.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/10-font/screenshot.png
:alt: example-10-font
`11-fontsdf <https://github.com/bkaradzic/bgfx/tree/master/examples/11-fontsdf>`__
----------------------------------------------------------------------------------
Use a single distance field font to render text of various size.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/11-fontsdf/screenshot.png
:alt: example-11-fontsdf
`12-lod <https://github.com/bkaradzic/bgfx/tree/master/examples/12-lod>`__
--------------------------------------------------------------------------
Mesh LOD transitions.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/12-lod/screenshot.png
:alt: example-12-lod
`13-stencil <https://github.com/bkaradzic/bgfx/tree/master/examples/13-stencil>`__
----------------------------------------------------------------------------------
Stencil reflections and shadows.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/13-stencil/screenshot.png
:alt: example-13-stencil
`14-shadowvolumes <https://github.com/bkaradzic/bgfx/tree/master/examples/14-shadowvolumes>`__
----------------------------------------------------------------------------------------------
Shadow volumes.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/14-shadowvolumes/screenshot.png
:alt: example-14-shadowvolumes
`15-shadowmaps-simple <https://github.com/bkaradzic/bgfx/tree/master/examples/15-shadowmaps-simple>`__
------------------------------------------------------------------------------------------------------
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/15-shadowmaps-simple/screenshot.png
:alt: example-15-shadowmaps-simple
`16-shadowmaps <https://github.com/bkaradzic/bgfx/tree/master/examples/16-shadowmaps>`__
----------------------------------------------------------------------------------------
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/16-shadowmaps/screenshot.png
:alt: example-16-shadowmaps
`17-drawstress <https://github.com/bkaradzic/bgfx/blob/master/examples/17-drawstress>`__
----------------------------------------------------------------------------------------
60Hz
^^^^
Draw stress is CPU stress test to show what is the maximimum number of
draw calls while maintaining 60Hz frame rate. bgfx currently has default
limit of 64K draw calls per frame. You can increase this limit by
changing ``BGFX_CONFIG_MAX_DRAW_CALLS``.
+-----------------+----------------+--------------+------------------------+-------+----------+
| CPU | Renderer | GPU | Arch/Compiler/OS | Dim | Calls |
+=================+================+==============+========================+=======+==========+
| i7-4770K 4.2 | GL2.1 | 2xGTX780 | x64/VS2013/Win 8.1 | 51 | 132651 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-4770K 4.2 | DX11 | 2xGTX780 | x64/VS2013/Win 8.1 | 50 | 125000 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-4790K 4.0 | GL2.1 | GTX970 | x64/VS2015/Win 10 | 47 | 103823 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-4790K 4.0 | DX11 | GTX970 | x64/VS2015/Win 10 | 45 | 91125 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-4790K 4.0 | DX9 | GTX970 | x64/VS2013/Win 10 | 40 | 64000 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i5-3570 3.8 | NV 331.49 | GTX560Ti | x64/GCC/Linux | 40 | 64000+ |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | GL2.1 | GTX650Ti | x64/VS2008/Win 7 | 38 | 54872 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | GL2.1 | GTX650Ti | x86/VS2008/Win 7 | 38 | 54872 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-6700K 4.0 | GL2.1 | Skylake GT2 | x64/GCC/Win 10 | 38 | 54872 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-4790K 4.0 | DX11 | R7 240 | x64/VS2015/Win 10 | 36 | 46656 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | NV 331.113 | GTX650Ti | x64/GCC/Linux | 34 | 39304 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-6700K 4.0 | DX11 | Skylake GT2 | x64/GCC/Win 10 | 34 | 39304 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-4790K 4.0 | DX9 | R7 240 | x64/VS2015/Win 10 | 32 | 32768 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | DX9 | GTX650Ti | x64/GCC/Win 7 | 32 | 32768 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | DX9 | GTX650Ti | x64/VS2008/Win 7 | 32 | 32768 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | DX9 | GTX650Ti | x86/GCC/Win 7 | 30 | 27000 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | DX9 | GTX650Ti | x86/VS2008/Win 7 | 30 | 27000 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i5-6200U 2.3 | DX11 | Intel 520 | x64/GCC/Win 10 | 30 | 27000 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i5-4250U 1.3 | GL2.1 | HD5000 | x64/Clang/OSX 10.9 | 28 | 21852 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| Q8200 2.33 | NV 319.32 | GTX260 | x64/GCC/Linux | 27 | 19683 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-6700K 4.0 | GL2.1 | Skylake GT2 | x64/GCC/Linux | 27 | 19683 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-2600K 3.4 | DX9 | AMD6800 | x64/VS2012/Win 7 | 27 | 19683 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-2600K 3.4 | GL2.1 | AMD6800 | x64/VS2012/Win 7 | 26 | 17576 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-4770R 3.2 | Mesa 10.5.9 | HD5200 | x64/GCC/Linux | 26 | 17576 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i5-6200U 2.3 | GL | Intel 520 | x64/GCC/Win 10 | 26 | 17576 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | DX9-Wine | GTX650Ti | x64/GCC/Linux | 24 | 13824 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i5-6200U 2.3 | Mesa 10.5.9 | Intel 520 | x64/GCC/Linux | 23 | 12167 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-4750HQ 2.0 | Mesa 10.0.1 | HD5200 | x64/GCC/Linux | 22 | 10648 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-4750HQ 2.0 | Mesa 10.1.3 | HD5200 | x64/GCC/Linux | 21 | 9261 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | ES2-ANGLE | GTX650Ti | x86/VS2008/Win 7 | 21 | 9261 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| Q8200 2.33 | Gallium 0.4 | AMD5770 | x64/GCC/Linux | 21 | 9261 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i5-4250U 1.3 | ES2 | HD5000 | JIT/Clang/PNaCl 31 | 21 | 9261 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i5-4250U 1.3 | ES2 | HD5000 | x86/GCC/NaCl 31 | 20 | 8000 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| Q8200 2.33 | Gallium 0.4 | GTX260 | x64/GCC/Linux | 19 | 6859 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i5-2450M 2.5 | Mesa 10.2.0 | HD3000 | x64/GCC/Linux | 19 | 6859 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | ES2-PowerVR | GTX650Ti | x86/VS2008/Win 7 | 18 | 5832 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | FF27-GL | GTX650Ti | JIT/Clang/W7-asm.js | 17 | 4913 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-6700K 4.0 | DX9 | Skylake GT2 | x64/GCC/Win 10 | 16 | 4096 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-4750HQ 2.0 | Mesa 8.0.5 | LLVMPIPE | x64/GCC/Linux | 16 | 4096 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i5-6200U 2.3 | DX9 | Intel 520 | x64/GCC/Win 10 | 16 | 4096 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | ES2-Qualcomm | GTX650Ti | x86/VS2008/Win 7 | 15 | 3375 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | ES2 | GTX650Ti | x64/GCC/NaCl 31 | 15 | 3375 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | ES2 | GTX650Ti | JIT/Clang/PNaCl 31 | 15 | 3375 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| Q8200 2.33 | NV 319.32 | GTX260 | x64/GCC/NaCl 31 | 15 | 3375 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| Q8200 2.33 | NV 319.32 | GTX260 | x64/GCC/PNaCl 31 | 15 | 3375 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| '12 Nexus 7 | ES2 | Tegra3 | ARM/GCC/Android | 15 | 3375 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i5-4250U 1.3 | ES2-FF27 | HD5000 | JIT/Clang/OSX-asm.js | 15 | 3375 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i5-4250U 1.3 | Chrome33 | HD5000 | JIT/Clang/OSX-asm.js | 15 | 3375 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| iPad mini 2 | ES2 | PVR G6430 | ARM64/Clang/iOS7 | 15 | 3375 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | Chrome33 | GTX650Ti | JIT/Clang/W7-asm.js | 14 | 2744 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | FF27-ANGLE | GTX650Ti | JIT/Clang/W7-asm.js | 14 | 2744 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| '13 Nexus 10 | ES2 | Mali T604 | ARM/GCC/Android | 13 | 2197 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| iPhone 5 | ES2 | PVR SGX543 | ARM/Clang/iOS7 | 13 | 2197 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| '13 Nexus 7 | ES2 | S4 Pro | ARM/GCC/Android | 12 | 1728 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| iPad 2 | ES2 | PVR SGX543 | ARM/Clang/iOS6 | 12 | 1728 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| AMD A4-5000 | Gallium 0.4 | HD8330/Kabini| x64/GCC/Linux | 12 | 1728 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| Xperia Z | ES2 | Adreno320 | ARM/GCC/Android | 11 | 1331 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| iPod 4 | ES2 | PVR SGX535 | ARM/Clang/iOS6 | 7 | 343 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i7-920 2.66 | ES2-Mali | GTX650Ti | x86/VS2008/Windows7 | 6 | 216 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| Creator CI20 | ES2 | PVR SGX540 | MIPS/GCC/Debian8 | 7 | 343 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| i5-6200U 2.3 | ES2 | SwiftShader | x64/GCC/Linux | 6 | 216 |
+-----------------+----------------+--------------+------------------------+-------+----------+
| RaspberryPi | ES2 | VC IV | ARM/GCC/Raspbian | 6 | 216 |
+-----------------+----------------+--------------+------------------------+-------+----------+
To test browsers in 60Hz mode following changes were made:
- Firefox 27 about:config adjustments: ``webgl.prefer-native-gl true``
(on Windows), and ``layout.frame_rate 500``.
- Chrome 33 command line option: ``--disable-gpu-vsync``.
30Hz (test for browsers)
^^^^^^^^^^^^^^^^^^^^^^^^
By default browsers are using vsync, and don't have option to turn it
off programatically.
+----------------+------------+------------+--------------------------+-------+----------+
| CPU | Renderer | GPU | Arch/Compiler/OS | Dim | Calls |
+================+============+============+==========================+=======+==========+
| i7-920 2.66 | GL2.1 | GTX650Ti | x64/VS2008/Win7 | 38 | 64000+ |
+----------------+------------+------------+--------------------------+-------+----------+
| i5-4250U 1.3 | GL2.1 | HD5000 | x64/Clang/OSX 10.9 | 36 | 46656 |
+----------------+------------+------------+--------------------------+-------+----------+
| i5-4250U 1.3 | Chrome34 | HD5000 | JIT/Clang/OSX-PNaCl 31 | 28 | 21952 |
+----------------+------------+------------+--------------------------+-------+----------+
| i5-4250U 1.3 | Chrome33 | HD5000 | JIT/Clang/OSX-PNaCl 31 | 27 | 19683 |
+----------------+------------+------------+--------------------------+-------+----------+
| i5-4250U 1.3 | FF28 | HD5000 | JIT/Clang/OSX-asm.js | 25 | 15625 |
+----------------+------------+------------+--------------------------+-------+----------+
| i5-4250U 1.3 | FF36 | HD5000 | JIT/Clang/OSX-asm.js | 25 | 15625 |
+----------------+------------+------------+--------------------------+-------+----------+
| i5-4250U 1.3 | Chrome41 | HD5000 | x64/GCC/OSX-NaCl 41 | 24 | 13824 |
+----------------+------------+------------+--------------------------+-------+----------+
| i5-4250U 1.3 | FF37 | HD5000 | JIT/Clang/OSX-asm.js | 23 | 12167 |
+----------------+------------+------------+--------------------------+-------+----------+
| i5-4250U 1.3 | FF27 | HD5000 | JIT/Clang/OSX-asm.js | 20 | 8000 |
+----------------+------------+------------+--------------------------+-------+----------+
| i7-920 2.66 | Chrome33 | GTX650Ti | JIT/Clang/W7-PNaCl 31 | 20 | 8000 |
+----------------+------------+------------+--------------------------+-------+----------+
| i7-920 2.66 | Chrome34 | GTX650Ti | JIT/Clang/W7-asm.js | 18 | 5832 |
+----------------+------------+------------+--------------------------+-------+----------+
| i7-920 2.66 | Chrome33 | GTX650Ti | JIT/Clang/W7-asm.js | 18 | 5832 |
+----------------+------------+------------+--------------------------+-------+----------+
| i7-920 2.66 | FF28 | GTX650Ti | JIT/Clang/W7-asm.js | 18 | 5832 |
+----------------+------------+------------+--------------------------+-------+----------+
| i7-920 2.66 | FF27 | GTX650Ti | JIT/Clang/W7-asm.js | 18 | 5832 |
+----------------+------------+------------+--------------------------+-------+----------+
| i5-4250U 1.3 | Safari7 | HD5000 | JIT/Clang/OSX-asm.js | 15 | 3375 |
+----------------+------------+------------+--------------------------+-------+----------+
`18-ibl <https://github.com/bkaradzic/bgfx/tree/master/examples/18-ibl>`__
--------------------------------------------------------------------------
Image-based lighting.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/18-ibl/screenshot.png
:alt: example-18-ibl
`19-oit <https://github.com/bkaradzic/bgfx/tree/master/examples/19-oit>`__
--------------------------------------------------------------------------
Weighted, Blended Order-Independent Transparency
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/19-oit/screenshot.png
:alt: example-19-oit
`20-nanovg <https://github.com/bkaradzic/bgfx/tree/master/examples/20-nanovg>`__
--------------------------------------------------------------------------------
NanoVG is small antialiased vector graphics rendering library.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/20-nanovg/screenshot.png
:alt: example-20-nanovg
`21-deferred <https://github.com/bkaradzic/bgfx/tree/master/examples/21-deferred>`__
------------------------------------------------------------------------------------
MRT rendering and deferred shading.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/21-deferred/screenshot.png
:alt: example-21-deferred
`22-windows <https://github.com/bkaradzic/bgfx/tree/master/examples/22-windows>`__
----------------------------------------------------------------------------------
Rendering into multiple windows.
`23-vectordisplay <https://github.com/bkaradzic/bgfx/tree/master/examples/23-vectordisplay>`__
----------------------------------------------------------------------------------------------
Rendering lines as oldschool vectors.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/23-vectordisplay/screenshot.png
:alt: example-23-vectordisplay
`24-nbody <https://github.com/bkaradzic/bgfx/tree/master/examples/24-nbody>`__
------------------------------------------------------------------------------
N-body simulation with compute shaders using buffers.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/24-nbody/screenshot.png
:alt: example-24-nbody
`25-c99 <https://github.com/bkaradzic/bgfx/tree/master/examples/25-c99>`__
--------------------------------------------------------------------------
Initialization and debug text with C99 API.
`26-occlusion <https://github.com/bkaradzic/bgfx/tree/master/examples/26-occlusion>`__
--------------------------------------------------------------------------------------
Using occlusion query for conditional rendering.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/26-occlusion/screenshot.png
:alt: example-26-occlusion
`27-terrain <https://github.com/bkaradzic/bgfx/tree/master/examples/27-terrain>`__
----------------------------------------------------------------------------------
Terrain painting example.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/27-terrain/screenshot.png
:alt: example-27-terrain
`28-wireframe <https://github.com/bkaradzic/bgfx/tree/master/examples/28-wireframe>`__
--------------------------------------------------------------------------------------
Drawing wireframe mesh.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/28-wireframe/screenshot.png
:alt: example-28-wireframe
`29-debugdraw <https://github.com/bkaradzic/bgfx/tree/master/examples/29-debugdraw>`__
--------------------------------------------------------------------------------------
Debug draw.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/29-debugdraw/screenshot.png
:alt: example-29-debugdraw
`30-picking <https://github.com/bkaradzic/bgfx/tree/master/examples/30-picking>`__
--------------------------------------------------------------------------------------
Mouse picking via GPU readback.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/30-picking/screenshot.png
:alt: example-30-picking
`31-rsm <https://github.com/bkaradzic/bgfx/tree/master/examples/31-rsm>`__
--------------------------------------------------------------------------------------
Global Illumination with Reflective Shadow Map.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/31-rsm/screenshot.png
:alt: example-31-rsm
`32-particles <https://github.com/bkaradzic/bgfx/tree/master/examples/32-particles>`__
--------------------------------------------------------------------------------------
Particles.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/32-particles/screenshot.png
:alt: example-32-particles
`33-pom <https://github.com/bkaradzic/bgfx/tree/master/examples/33-pom>`__
--------------------------------------------------------------------------
Parallax occlusion mapping.
Reference(s):
- `Exploring bump mapping with WebGL <http://apoorvaj.io/exploring-bump-mapping-with-webgl.html>`__
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/33-pom/screenshot.png
:alt: example-33-pom
`34-mvs <https://github.com/bkaradzic/bgfx/tree/master/examples/34-mvs>`__
--------------------------------------------------------------------------
Multiple vertex streams.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/34-mvs/screenshot.png
:alt: example-34-mvs
`35-dynamic <https://github.com/bkaradzic/bgfx/tree/master/examples/35-dynamic>`__
----------------------------------------------------------------------------------
Dynamic buffers update.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/35-dynamic/screenshot.png
:alt: example-35-dynamic
`36-sky <https://github.com/bkaradzic/bgfx/tree/master/examples/36-sky>`__
--------------------------------------------------------------------------
Perez dynamic sky model.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/36-sky/screenshot.png
:alt: example-36-sky
`37-gpudrivenrendering <https://github.com/bkaradzic/bgfx/tree/master/examples/37-gpudrivenrendering>`__
--------------------------------------------------------------------------------------------------------
GPU-Driven Rendering.
Reference(s):
- `Experiments in GPU-based occlusion culling <https://interplayoflight.wordpress.com/2017/11/15/experiments-in-gpu-based-occlusion-culling/>`__,
- `Experiments in GPU-based occlusion culling part 2: MultiDrawIndirect and mesh lodding <https://interplayoflight.wordpress.com/2018/01/15/experiments-in-gpu-based-occlusion-culling-part-2-multidrawindirect-and-mesh-lodding/>`__,
- `Porting GPU driven occlusion culling to bgfx <https://interplayoflight.wordpress.com/2018/03/05/porting-gpu-driven-occlusion-culling-to-bgfx/>`__.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/37-gpudrivenrendering/screenshot.png
:alt: example-37-gpudrivenrendering
`38-bloom <https://github.com/bkaradzic/bgfx/tree/master/examples/38-bloom>`__
------------------------------------------------------------------------------
Bloom.
Reference(s):
- `Next Generation Post Processing in Call of Duty: Advanced Warfare <http://www.iryoku.com/next-generation-post-processing-in-call-of-duty-advanced-warfare>`__.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/38-bloom/screenshot.png
:alt: example-38-bloom
`39-assao <https://github.com/bkaradzic/bgfx/tree/master/examples/39-assao>`__
------------------------------------------------------------------------------
Adaptive Screen Space Ambient Occlusion.
Reference(s):
- `Adaptive Screen Space Ambient Occlusion <https://software.intel.com/en-us/articles/adaptive-screen-space-ambient-occlusion>`__.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/39-assao/screenshot.png
:alt: example-39-assao
`40-svt <https://github.com/bkaradzic/bgfx/tree/master/examples/40-svt>`__
--------------------------------------------------------------------------
Sparse Virtual Textures.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/40-svt/screenshot.png
:alt: example-40-svt
`41-tess <https://github.com/bkaradzic/bgfx/tree/master/examples/41-tess>`__
----------------------------------------------------------------------------
Adaptive GPU Tessellation with Compute Shaders
Reference(s):
- `Adaptive GPU Tessellation with Compute Shaders by Jad Khoury, Jonathan Dupuy, and Christophe Riccio <http://onrendering.com/data/papers/isubd/isubd.pdf>`__.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/41-tess/screenshot.png
:alt: example-41-tess
`42-bunnylod <https://github.com/bkaradzic/bgfx/tree/master/examples/42-bunnylod>`__
------------------------------------------------------------------------------------
Simple Polygon Reduction
Reference(s):
- `Simple Polygon Reduction <https://web.archive.org/web/20020114194131/http://www.melax.com/polychop/>`__.
- `A Simple, Fast,and Effective Polygon Reduction Algorithm <https://web.archive.org/web/20031204035320/http://www.melax.com/polychop/gdmag.pdf>`__.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/42-bunnylod/screenshot.png
:alt: example-42-bunnylod
`43-denoise <https://github.com/bkaradzic/bgfx/tree/master/examples/43-denoise>`__
----------------------------------------------------------------------------------
Denoise
Reference(s):
- `Spatiotemporal Variance-Guided Filtering: Real-Time Reconstruction for Path-Traced Global Illumination. <https://web.archive.org/web/20170720213354/https://research.nvidia.com/sites/default/files/pubs/2017-07_Spatiotemporal-Variance-Guided-Filtering%3A/svgf_preprint.pdf>`__.
- `Streaming G-Buffer Compression for Multi-Sample Anti-Aliasing <https://web.archive.org/web/20200807211002/https://software.intel.com/content/www/us/en/develop/articles/streaming-g-buffer-compression-for-multi-sample-anti-aliasing.html>`__.
- `Edge-Avoiding À-Trous Wavelet Transform for fast Global Illumination Filtering <https://web.archive.org/web/20130412085423/https://www.uni-ulm.de/fileadmin/website_uni_ulm/iui.inst.100/institut/Papers/atrousGIfilter.pdf>`__.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/43-denoise/screenshot.png
:alt: example-43-denoise
`44-sss <https://github.com/bkaradzic/bgfx/tree/master/examples/44-sss>`__
--------------------------------------------------------------------------
Screen-Space Shadows
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/44-sss/screenshot.png
:alt: example-44-sss
`45-bokeh <https://github.com/bkaradzic/bgfx/tree/master/examples/45-bokeh>`__
------------------------------------------------------------------------------
Bokeh Depth of Field
Reference(s):
- `Bokeh depth of field in a single pass <https://web.archive.org/web/20201215123940/https://blog.tuxedolabs.com/2018/05/04/bokeh-depth-of-field-in-single-pass.html>`__.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/45-bokeh/screenshot.png
:alt: example-45-bokeh
`46-fsr <https://github.com/bkaradzic/bgfx/tree/master/examples/46-fsr>`__
------------------------------------------------------------------------------
AMD FidelityFX Super Resolution - high-quality solution for producing high resolution frames
from lower resolution inputs.
.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/46-fsr/screenshot.png
:alt: example-46-fsr

22
docs/index.rst Normal file
View File

@ -0,0 +1,22 @@
Documentation
=============
Cross-platform, graphics API agnostic, “Bring Your Own Engine/Framework” style rendering library,
licensed under permissive BSD-2 clause open source license.
Source at GitHub:
- https://github.com/bkaradzic/bgfx
Contents
--------
.. toctree::
:maxdepth: 3
overview
build
examples
bgfx
tools
internals
license

50
docs/internals.rst Normal file
View File

@ -0,0 +1,50 @@
Internals
=========
Sort based draw call bucketing
------------------------------
bgfx is using sort-based draw call bucketing. This means that submission order doesn't necessarily match the rendering order, but on the low-level they will be sorted and ordered correctly. On the high level bgfx uses **declarative API** and internal sorting allows more optimal way of submitting draw calls for all passes at one place, and on the low-level this allows better optimization of rendering order. This sometimes creates undesired results usually for GUI rendering, where draw order should usually match submit order. bgfx provides way to enable sequential rendering for these cases (see ``bgfx::setViewMode``).
- More detailed description of sort-based draw call bucketing can be found at: `Order your graphics draw calls around! <http://realtimecollisiondetection.net/blog/?p=86>`__
API and render thread
---------------------
API thread is thread from which ``bgfx::init`` is called. Once ``bgfx::init`` is called on thread, internally bgfx assumes that all API calls will be called from the same thread with exception of Resource, View, and Encoder API.
Render thread from where internal rendering ``bgfx::renderFrame`` is called. On most of OS' it's required that this call be called on thread that OS created when executing process (some refer to this thread as "main" thread, or thread where ``main`` function is called).
When bgfx is compiled with option ``BGFX_CONFIG_MULTITHREADED=1`` (default is on) ``bgfx::renderFrame`` can be called by user. It's required to be called before ``bgfx::init`` from thread that will be used as render thread. If both ``bgfx::renderFrame`` and ``bgfx::init`` are called from the same thread, bgfx will switch to execute in single threaded mode, and calling ``bgfx::renderFrame`` is not required, since it will be called automatically during ``bgfx::frame`` call.
Resource API
------------
Any API call starting with ``bgfx::create*``, ``bgfx::destroy*``, ``bgfx::update*``, ``bgfx::alloc*`` is considered part of resource API. Internally resource API calls are guarded by mutex. There is no limit of number of threads that can call resource API simultaneously. Calling any resource API is infrequent, and functions are cheap since most of work with resource is done at later point on render thread.
View API
--------
Any API call starting with ``bgfx::setView*`` is considered part of view API. View API is not designed to be thread safe at all since all views are independentent from each other. Calling any view API for different views from different threads is safe. What's not safe is to update the same view from multiple threads. This will lead to undefined behavior. Only view API that has to be set before any draw calls are issued is view mode ``bgfx::setViewMode``. Internal encoder requires view mode to select sort key encoding and if user changes view mode after submit it will cause incorrect sort behavior within the view.
Encoder API
-----------
Encoder API can be obtained by calling ``bgfx::begin``. bgfx by default allows 8 simultaneous threads to use encoders. This can be configured by changing ``Limits.maxEncoders`` init option of ``bgfx::Init`` structure.
Customization
-------------
By default each platform has sane default values. For example on Windows default renderer is DirectX, on Linux it is OpenGL, and on OSX it's Metal. On Windows platform almost all rendering backends are available. For OpenGL ES on desktop you can find more information at:- `OpenGL ES 2.0 and EGL on desktop <http://www.g-truc.net/post-0457.html>`__
If you're targeting specific mobile hardware, you can find GLES support in their official SDKs: `Adreno
SDK <http://developer.qualcomm.com/mobile-development/mobile-technologies/gaming-graphics-optimization-adreno/tools-and-resources>`__, `Mali SDK <http://www.malideveloper.com/>`__, `PowerVR SDK <http://www.imgtec.com/powervr/insider/sdkdownloads/>`__.
All configuration settings are located inside `src/config.h <https://github.com/bkaradzic/bgfx/blob/master/src/config.h>`__.
Every ``BGFX_CONFIG_*`` setting can be changed by passing defines thru compiler switches. For example setting preprocessor define ``BGFX_CONFIG_RENDERER_OPENGL=1`` will change backend renderer to OpenGL 2.1. on Windows. Since rendering APIs are platform specific, this obviously won't work nor make sense in all cases.
Options
~~~~~~~
``BGFX_CONFIG_MULTITHREADED`` is used to enable/disable threading support inside bgfx. By default set to 1 on all platforms that support threading.

185
docs/license.rst Normal file
View File

@ -0,0 +1,185 @@
License
=======
`License (BSD 2-clause) <https://github.com/bkaradzic/bgfx/blob/master/LICENSE>`__
----------------------------------------------------------------------------------
::
Copyright 2010-2020 Branimir Karadzic
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.
3rd Party Libraries
-------------------
All required 3rd party libraries are included in bgfx repository in
`3rdparty/ <https://github.com/bkaradzic/bgfx/tree/master/3rdparty>`__
directory.
Blendish (MIT)
~~~~~~~~~~~~~~
Blendish - Blender 2.5 UI based theming functions for NanoVG.
- https://bitbucket.org/duangle/oui-blendish
edtaa3 (MIT)
~~~~~~~~~~~~
Contour Rendering by Distance Fields
- https://github.com/OpenGLInsights/OpenGLInsightsCode/tree/master/Chapter%2012%202D%20Shape%20Rendering%20by%20Distance%20Fields
fcpp (BSD)
~~~~~~~~~~
Frexx C preprocessor
- https://github.com/bagder/fcpp
Forsyth Triangle Order Optimizer (Public Domain)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- http://gameangst.com/?p=9
FreeType
~~~~~~~~
- http://www.freetype.org/
glsl-optimizer (MIT)
~~~~~~~~~~~~~~~~~~~~
GLSL optimizer based on Mesa's GLSL compiler. Used in Unity for mobile
shader optimization.
- https://github.com/aras-p/glsl-optimizer
NanoVG (ZLIB)
~~~~~~~~~~~~~
NanoVG is small antialiased vector graphics rendering library.
- https://github.com/memononen/nanovg
ImGui (MIT)
~~~~~~~~~~~
Bloat-free Immediate Mode Graphical User interface for C++ with minimal
dependencies.
- https://github.com/ocornut/imgui
SDF (MIT)
~~~~~~~~~
Sweep-and-update Euclidean distance transform of an antialised image for
contour texturing.
- https://github.com/memononen/SDF
stb (Public Domain)
~~~~~~~~~~~~~~~~~~~
- http://nothings.org
Vertex Cache Optimised Index Buffer Compression (BSD)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- https://github.com/ConorStokes/IndexBufferCompression
Assets
------
Bunny
- `Stanford University Computer Graphics Laboratory <http://www-graphics.stanford.edu/data/3Dscanrep/>`__
Uffizi
- `Light Probe Image Gallery <http://www.pauldebevec.com/Probes/>`__
Wells
- `Bernhard Vogl Light probes <http://dativ.at/lightprobes/>`__
Pisa, Ennis, Grace
- `High-Resolution Light Probe Image Gallery <http://gl.ict.usc.edu/Data/HighResProbes/>`__
Droid Sans Font
- http://www.fontsquirrel.com/license/Droid-Sans
Bleeding Cowboys Font
- http://www.dafont.com/bleeding-cowboys.font
Cheap Fire Font
- http://www.dafont.com/cheap-fire.font
Five Minutes Font
- http://www.fonts2u.com/fiveminutes.font
Mias Scribblings Font
- http://www.dafont.com/mias-scribblings.font
Ruritania Font
- http://www.dafont.com/ruritania.font
Signika Font
- http://fontfabric.com/signika-font/
Visitor Font
- http://www.dafont.com/visitor.font
Special-Elite Font
- http://www.fontspace.com/astigmatic-one-eye-typographic-institute/special-elite
FontAwesome Font
- http://fontawesome.io/
Sherlock Holmes text
- http://www.gutenberg.org/ebooks/1661
Tree Pack 1
- http://www.turbosquid.com/3d-models/free-obj-mode-tree-pack/506851
Light Transport Equation Orb
- https://github.com/lighttransport/lighttransportequation-orb
Normal map texture (GFDL License)
- `Julian Herzog <https://julianherzog.com/>`__
- https://commons.wikimedia.org/wiki/File:Normal_map_example_with_scene_and_result.png

292
docs/overview.rst Normal file
View File

@ -0,0 +1,292 @@
Overview
========
What is it?
-----------
Cross-platform, graphics API agnostic, "Bring Your Own Engine/Framework" style rendering library,
licensed under permissive BSD-2 clause open source license.
.. raw:: html
<p>
<iframe src="https://ghbtns.com/github-btn.html?user=bkaradzic&repo=bgfx&type=star&count=true&size=large" frameborder="0" scrolling="0" width="160px" height="30px"></iframe>
<iframe src="https://ghbtns.com/github-btn.html?user=bkaradzic&repo=bgfx&type=fork&count=true&size=large" frameborder="0" scrolling="0" width="158px" height="30px"></iframe>
</p>
Supported rendering backends
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Direct3D 9
- Direct3D 11
- Direct3D 12
- GNM (only for licensed PS4 developers, search DevNet forums for source)
- Metal
- OpenGL 2.1
- OpenGL 3.1+
- OpenGL ES 2
- OpenGL ES 3.1
- Vulkan
- WebGL 1.0
- WebGL 2.0
- WebGPU/Dawn (experimental)
Supported Platforms
~~~~~~~~~~~~~~~~~~~
- Android (14+, ARM, x86, MIPS)
- asm.js/Emscripten (1.25.0)
- FreeBSD
- iOS (iPhone, iPad, AppleTV)
- Linux
- MIPS Creator CI20
- OSX (10.12+)
- PlayStation 4
- RaspberryPi
- Windows (XP, Vista, 7, 8, 10)
- UWP (Universal Windows, Xbox One)
Supported Compilers
~~~~~~~~~~~~~~~~~~~
- Clang 3.3 and above
- GCC 5 and above
- vs2017 and above
Supported Languages
~~~~~~~~~~~~~~~~~~~
- `C/C++ API documentation <https://bkaradzic.github.io/bgfx/bgfx.html>`__
- `C# language API bindings #1 <https://github.com/bkaradzic/bgfx/tree/master/bindings/cs>`__
- `C#/VB/F# language API bindings #2 <https://github.com/MikePopoloski/SharpBgfx>`__
- `D language API bindings <https://github.com/GoaLitiuM/bindbc-bgfx>`__
- `Go language API bindings <https://github.com/james4k/go-bgfx>`__
- `Haskell language API bindings <https://github.com/haskell-game/bgfx>`__
- `Lightweight Java Game Library 3 bindings <https://github.com/LWJGL/lwjgl3#lwjgl---lightweight-java-game-library-3>`__
- `Lua language API bindings <https://github.com/cloudwu/lua-bgfx>`__
- `Nim language API bindings <https://github.com/Halsys/nim-bgfx>`__
- `Python language API bindings #1 <https://github.com/fbertola/bgfx-python#-----bgfx-python-->`__
- `Python language API bindings #2 <https://github.com/jnadro/pybgfx#pybgfx>`__
- `Rust language API bindings <https://github.com/rhoot/bgfx-rs#bgfx-rs>`__
- `Swift language API bindings <https://github.com/stuartcarnie/SwiftBGFX>`__
- `Pascal language API bindings <https://github.com/Akira13641/PasBGFX>`__
Project Page
~~~~~~~~~~~~
- https://github.com/bkaradzic/bgfx
Contact
~~~~~~~
- `GitHub Discussions <https://github.com/bkaradzic/bgfx/discussions>`__
- `Discord Chat <https://discord.gg/9eMbv7J>`__
- GitHub `@bkaradzic <https://github.com/bkaradzic>`__
- Twitter `@bkaradzic <https://twitter.com/bkaradzic>`__
Debugging and Profiling
-----------------------
RenderDoc
~~~~~~~~~
Loading of RenderDoc is integrated in bgfx when using DX11 or OpenGL
renderer. You can drop in ``renderdoc.dll`` from RenderDoc distribution
into working directory, and it will be automatically loaded during bgfx
initialization. This allows frame capture at any time by pressing
**F11**.
Download: `RenderDoc <https://renderdoc.org/builds>`__
RenderDoc `How do I ...? <https://renderdoc.org/docs/how/index.html>`__ documentation.
`Shader debugging <https://software.intel.com/en-us/articles/shader-debugging-for-bgfx-rendering-engine>`__
with RenderDoc and MSVC.
IntelGPA
~~~~~~~~
Right click **Intel GPA Monitor** tray icon, choose preferences, check
"Auto-detect launched applications" option. Find ``InjectionList.txt``
in GPA directory and add ``examples-*`` to the list.
Download:
`IntelGPA <https://software.intel.com/en-us/vcsource/tools/intel-gpa>`__
Other Debuggers and Profilers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. |x| unicode:: U+2713 .. CHECK MARK
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| Name | OS | DX9 | DX11 | DX12 | Metal | GL | GLES | Vulkan| Source |
+=============+=================+=======+========+======+=======+======+======+=======+========+
| APITrace | Linux/OSX/Win | |x| | |x| | | | |x| | |x| | | |x| |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| CodeXL | Linux/Win | | | | | |x| | | | |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| Dissector | Win | |x| | | | | | | | |x| |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| IntelGPA | Linux/OSX/Win | |x| | |x| | | | | |x| | | |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| Nsight | Win | |x| | |x| | | | |x| | | | |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| PerfHUD | Win | |x| | |x| | | | | | | |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| PerfStudio | Win | | |x| | |x| | | |x| | |x| | | |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| PIX | Win | | | |x| | | | | | |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| RGP | Win | | | |x| | | | | |x| | |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| RenderDoc | Win/Linux | | |x| | | | |x| | | |x| | |x| |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| vogl | Linux | | | | | |x| | | | |x| |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
Download:
- `APITrace <https://apitrace.github.io/>`__
- `CodeXL <http://developer.amd.com/tools-and-sdks/opencl-zone/codexl/>`__
- `Dissector <https://github.com/imccown/Dissector>`__
- `GPU PerfStudio <http://developer.amd.com/tools-and-sdks/graphics-development/gpu-perfstudio/>`__
- `Linux Graphics Debugger <https://developer.nvidia.com/linux-graphics-debugger>`__
- `Nsight <https://developer.nvidia.com/nsight-graphics>`__
- `PIX <https://blogs.msdn.microsoft.com/pix/>`__
- `PerfHUD <https://developer.nvidia.com/nvidia-perfhud>`__
- `RGP (Radeon GPU Profiler) <https://github.com/GPUOpen-Tools/Radeon-GPUProfiler/releases>`__
- `vogl <https://github.com/ValveSoftware/vogl>`__
SDL, GLFW, etc.
---------------
It is possible to use bgfx with SDL, GLFW and similar cross platform
windowing libraries. The main requirement is that windowing library
provides access to native window handle that's used to create Direct3D
device or OpenGL context.
For more info see: :doc:`bgfx`.
.. note:: You can use ``--with-sdl`` when runnning GENie to enable SDL2 integration with examples:
``genie --with-sdl vs2012``
.. note:: ``--with-glfw`` is also available, but it's just simple stub to be used to test GLFW
integration API.
.. note:: Special care is necessary to make custom windowing to work with multithreaded renderer.
Each platform has rules about where renderer can be and how multithreading interacts
with context/device. To disable multithreaded render use ``BGFX_CONFIG_MULTITHREADED=0``
preprocessor define.
Getting Involved
----------------
Everyone is welcome to contribute to bgfx by submitting bug reports, testing on different
platforms, writing examples (see `ideas <https://github.com/bkaradzic/bgfx/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+needed%22>`__),
improving documentation, profiling and optimizing, etc.
.. note:: **When contributing to the bgfx project you must agree to the BSD 2-clause
licensing terms.**
Contributors
~~~~~~~~~~~~
Chronological order:
- Branimir Karadžić (`@bkaradzic <https://github.com/bkaradzic>`__)
- Garett Bass (`@garettbass <https://github.com/garettbass>`__) - OSX port.
- Jeremie Roy (`@jeremieroy <https://github.com/jeremieroy>`__) -
`10-font <examples.html#font>`__,
and `11-fontsdf <examples.html#fontsdf>`__ examples.
- Miloš Tošić (`@milostosic <https://github.com/milostosic>`__) -
`12-lod <examples.html#lod>`__ example.
- Dario Manesku (`@dariomanesku <https://github.com/dariomanesku>`__) -
`13-stencil <examples.html#stencil>`__,
`14-shadowvolumes <examples.html#shadowvolumes>`__,
`15-shadowmaps-simple <examples.html#shadowmaps-simple>`__,
`16-shadowmaps <examples.html#shadowmaps>`__,
`18-ibl <examples.html#ibl>`__,
and `28-wireframe <examples.html#wireframe>`__ example.
- James Gray (`@james4k <https://github.com/james4k>`__) - Go language API bindings.
- Guillaume Piolat (`@p0nce <https://github.com/p0nce>`__) - D language API bindings.
- Mike Popoloski (`@MikePopoloski <https://github.com/MikePopoloski>`__) - C#/VB/F# language API
bindings, WinRT/WinPhone support.
- Kai Jourdan (`@questor <https://github.com/questor>`__) -
`23-vectordisplay <examples.html#vectordisplay>`__ example.
- Stanlo Slasinski (`@stanlo <https://github.com/stanlo>`__) -
`24-nbody <examples.html#nbody>`__ example.
- Daniel Collin (`@emoon <https://github.com/emoon>`__) - Port of Ocornut's ImGui to bgfx.
- Andre Weissflog (`@floooh <https://github.com/floooh>`__) - Alternative build system fips.
- Andrew Johnson (`@ajohnson23 <https://github.com/ajohnson23>`__) - TeamCity build.
- Tony McCrary (`@enleeten <https://github.com/enleeten>`__) - Java language API bindings.
- Attila Kocsis (`@attilaz <https://github.com/attilaz>`__) - Metal rendering backend, various OSX
and iOS improvements and bug fixes, `39-assao <examples.html#assao>`__ example.
- Richard Gale (`@RichardGale <https://github.com/RichardGale>`__) - Emscripten entry input
handling.
- Andrew Mac (`@andr3wmac <https://github.com/andr3wmac>`__) -
`27-terrain <examples.html#terrain>`__ example.
- Oliver Charles (`@ocharles <https://github.com/ocharles>`__) - Haskel language API bindings.
- Johan Sköld (`@rhoot <https://github.com/rhoot>`__) - Rust language API bindings.
- Jean-François Verdon (`@Nodrev <https://github.com/Nodrev>`__) - Alternative deployment for
Android.
- Jason Nadro (`@jnadro <https://github.com/jnadro>`__) - Python language API bindings.
- Krzysztof Kondrak (`@kondrak <https://github.com/kondrak>`__) - OculusVR integration.
- Colby Klein (`@excessive <https://github.com/excessive>`__) - Lua language API bindings.
- Stuart Carnie (`@stuartcarnie <https://github.com/stuartcarnie>`__) - Swift language API
bindings.
- Joseph Cherlin (`@jcherlin <https://github.com/jcherlin>`__) -
`30-picking <examples.html#picking>`__,
and `31-rsm <examples.html#rsm>`__ example.
- Olli Wang (`@olliwang <https://github.com/olliwang>`__) - Various NanoVG integration improvements.
- Cory Golden (`@Halsys <https://github.com/Halsys>`__) - Nim language API bindings.
- Camilla Berglund (`@elmindreda <https://github.com/elmindreda>`__) - GLFW support.
- Daniel Ludwig (`@code-disaster <https://github.com/code-disaster>`__) - Lightweight Java Game
Library 3 bindings.
- Benoit Jacquier (`@benoitjacquier <https://github.com/benoitjacquier>`__) - Added support for
cubemap as texture 2D array in a compute shader.
- Apoorva Joshi (`@ApoorvaJ <https://github.com/ApoorvaJ>`__) -
`33-pom <examples.html#pom>`__ example.
- Stanislav Pidhorsky (`@podgorskiy <https://github.com/podgorskiy>`__) -
`36-sky <examples.html#sky>`__ example.
- 云风 (`@cloudwu <https://github.com/cloudwu>`__) - Alternative Lua bindings, bgfx IDL scripts,
`42-bunnylod <examples.html#bunnylod>`__ example.
- Kostas Anagnostou (`@KostasAAA <https://github.com/KostasAAA>`__) -
`37-gpudrivenrendering <examples.html#gpudrivenrendering>`__ example.
- Andrew Willmott (`@andrewwillmott <https://github.com/andrewwillmott>`__) - ATC and ASTC support.
- Aleš Mlakar (`@jazzbre <https://github.com/jazzbre>`__) -
`40-svt <examples.html#svt>`__ example.
- Matt Chiasson (`@mchiasson <https://github.com/mchiasson>`__) - Various fixes and improvements.
- Phil Peron (`@pperon <https://github.com/pperon>`__) - Tutorial how to use bgfx API.
- Vincent Cruz (`@BlockoS <https://github.com/BlockoS>`__) - Wayland support.
- Jonathan Young (`@jpcy <https://github.com/jpcy>`__) - Renderer for ioquake3 that uses bgfx,
minimal bgfx example.
- Nick Waanders (`@NickWaanders <https://github.com/NickWaanders>`__) - shaderc: Metal fixes.
- Vladimir Vukićević (`@vvuk <https://github.com/vvuk>`__) - HTML5 context.
- Daniel Gavin (`@DanielGavin <https://github.com/DanielGavin>`__) - `41-tess <examples.html#tess>`__ example.
- Ji-yong Kwon (`@rinthel <https://github.com/rinthel>`__) - Vulkan rendering backend.
- Leandro Freire (`@leandrolfre <https://github.com/leandrolfre>`__).
- Ari Vuollet (`@GoaLitiuM <https://github.com/GoaLitiuM>`__) IDL generator for D language
bindings.
- Sebastian Marketsmueller (`@sebastianmunity3d <https://github.com/sebastianmunity3d>`__).
- Cedric Guillemet (`@CedricGuillemet <https://github.com/CedricGuillemet>`__).
- Pablo Escobar (`@pezcode <https://github.com/pezcode>`__) - Various Vulkan fixes.
- Paul Gruenbacher (`@pgruenbacher <https://github.com/pgruenbacher>`__) - Various bug fixes.
- Jukka Jylänki (`@juj <https://github.com/juj>`__) - Various WebGL optimizations and fixes.
- Hugo Amnov (`@hugoam <https://github.com/hugoam>`__) - WebGPU/Dawn rendering backend.
- Christophe Dehais (`@goodartistscopy <https://github.com/goodartistscopy>`__) - Various bug fixes.
- elvencache (`@elvencache <https://github.com/elvencache>`__) -
`43-denoise <examples.html#denoise>`__,
`44-sss <examples.html#sss>`__,
and `45-bokeh <examples.html#bokeh>`__ example.
- Richard Schubert (`@Hemofektik <https://github.com/Hemofektik/>`__) - `46-fsr <examples.html#fsr>`__ example.
and `others <https://github.com/bkaradzic/bgfx/graphs/contributors>`__...
Repository visualization
~~~~~~~~~~~~~~~~~~~~~~~~
.. raw:: html
<p>
<iframe width="694" height="390" src="https://www.youtube.com/embed/5ZeN_d_-BHo" frameborder="0" allowfullscreen></iframe>
</p>

161
docs/tools.rst Normal file
View File

@ -0,0 +1,161 @@
Tools
=====
Geometry Compiler (geometryc)
-----------------------------
Converts Wavefront .obj, or glTF 2.0 mesh file to format optimal for using with bgfx.
Usage::
geometryc -f <in> -o <out>
Supported input file formats:
====== ============================
Format Description
====== ============================
.obj Wavefront
.gltf glTF 2.0
.glb glTF 2.0
====== ============================
Options:
-h, --help Help.
-v, --version Version information only.
-f <file path> Input file path.
-o <file path> Output file path.
-s, --scale <num> Scale factor.
--ccw Front face is counter-clockwise winding order.
--flipv Flip texture coordinate V.
--obb <num> Number of steps for calculating oriented bounding box.
Default value is 17. Less steps less precise OBB is.
More steps slower calculation.
--packnormal <num> Normal packing.
0 - unpacked 12 bytes (default).
1 - packed 4 bytes.
--packuv <num> Texture coordinate packing.
0 - unpacked 8 bytes (default).
1 - packed 4 bytes.
--tangent Calculate tangent vectors (packing mode is the same as normal).
--barycentric Adds barycentric vertex attribute (packed in bgfx::Attrib::Color1).
-c, --compress Compress indices.
--[l/r]h-up+[y/z] Coordinate system. Default is '--lh-up+y' Left-Handed +Y is up.
Geometry Viewer (geometryv)
---------------------------
Geometry viewer.
Shader Compiler (shaderc)
-------------------------
bgfx cross-platform shader language is based on GLSL syntax. It's uses
ANSI C preprocessor to transform GLSL like language syntax into HLSL.
This technique has certain drawbacks, but overall it's simple and allows
quick authoring of cross-platform shaders.
Some differences between bgfx's shaderc flavor of GLSL and regular GLSL:
- No ``bool/int`` uniforms, all uniforms must be ``float``.
- Attributes and varyings can be accessed only from ``main()``
function.
- Must use ``SAMPLER2D/3D/CUBE/etc.`` macros instead of
``sampler2D/3D/Cube/etc.`` tokens.
- Must use ``vec2/3/4_splat(<value>)`` instead of
``vec2/3/4(<value>)``.
- Must use ``mtxFromCols/mtxFromRows`` when constructing matrices in shaders.
- Must use ``mul(x, y)`` when multiplying vectors and matrices.
- Must use ``varying.def.sc`` to define input/output semantic and
precission instead of using ``attribute/in`` and ``varying/in/out``.
- ``$input/$output`` tokens must appear at the begining of shader.
For more info see `shader helper
macros <https://github.com/bkaradzic/bgfx/blob/master/src/bgfx_shader.sh>`__.
Options:
-h, --help Help.
-v, --version Version information only.
-f <file path> Input file path.
-i <include path> Include path (for multiple paths use -i multiple times).
-o <file path> Output file path.
--bin2c <array name> Generate C header file. If array name is not specified base file name will be used as name.
--depends Generate makefile style depends file.
--platform <platform> Target platform.
-p, --profile <profile> Shader model (default GLSL).
--preprocess Preprocess only.
--define <defines> Add defines to preprocessor (semicolon separated).
--raw Do not process shader. No preprocessor, and no glsl-optimizer (GLSL only).
--type <type> Shader type (vertex, fragment, compute)
--varyingdef <file path> Path to varying.def.sc file.
--verbose Verbose.
Options (DX9 and DX11 only):
--debug Debug information.
--disasm Disassemble compiled shader.
-O <level> Optimization level (0, 1, 2, 3).
--Werror Treat warnings as errors.
Building shaders
~~~~~~~~~~~~~~~~
Shaders must be compiled for all renderers by using `shaderc` tool. Makefile to simplify building
shaders is provided in examples. D3D shaders can be only compiled on Windows.
Texture Compiler (texturec)
---------------------------
Convert PNG, TGA, DDS, KTX, PVR texture into bgfx supported texture formats.
Usage::
texturec -f <in> -o <out> [-t <texture format>]
Supported file formats:
====== ================ ============================
Format In/Out Description
====== ================ ============================
.bmp (input) Windows Bitmap.
.dds (input, output) Direct Draw Surface.
.exr (input, output) OpenEXR.
.gif (input) Graphics Interchange Format.
.jpg (input) JPEG Interchange Format.
.hdr (input, output) Radiance RGBE.
.ktx (input, output) Khronos Texture.
.png (input, output) Portable Network Graphics.
.psd (input) Photoshop Document.
.pvr (input) PowerVR.
.tga (input) Truevision TGA.
====== ================ ============================
Options:
-h, --help Help.
-v, --version Version information only.
-f <file path> Input file path.
-o <file path> Output file path.
-t <format> Output format type (BC1/2/3/4/5, ETC1, PVR14, etc.).
-q <quality> Encoding quality (default, fastest, highest).
-m, --mips Generate mip-maps.
--mipskip <N> Skip <N> number of mips.
-n, --normalmap Input texture is normal map. (Implies --linear)
--equirect Input texture is equirectangular projection of cubemap.
--strip Input texture is horizontal strip of cubemap.
--sdf Compute SDF texture.
--ref <alpha> Alpha reference value.
--iqa Image Quality Assessment
--pma Premultiply alpha into RGB channel.
--linear Input and output texture is linear color space (gamma correction won't be applied).
--max <max size> Maximum width/height (image will be scaled down and aspect ratio will be preserved).
--radiance <model> Radiance cubemap filter. (Lighting model: Phong, PhongBrdf, Blinn, BlinnBrdf, GGX)
--as <extension> Save as.
--formats List all supported formats.
--validate **DEBUG** Validate that output image produced matches after loading.
Texture Viewer (texturev)
-------------------------
Texture viewer.