diff options
Diffstat (limited to '3rdparty/bgfx/docs')
-rw-r--r-- | 3rdparty/bgfx/docs/bgfx.rst | 605 | ||||
-rw-r--r-- | 3rdparty/bgfx/docs/build.rst | 215 | ||||
-rw-r--r-- | 3rdparty/bgfx/docs/examples.rst | 706 | ||||
-rw-r--r-- | 3rdparty/bgfx/docs/index.rst | 22 | ||||
-rw-r--r-- | 3rdparty/bgfx/docs/internals.rst | 50 | ||||
-rw-r--r-- | 3rdparty/bgfx/docs/license.rst | 132 | ||||
-rw-r--r-- | 3rdparty/bgfx/docs/overview.rst | 300 | ||||
-rw-r--r-- | 3rdparty/bgfx/docs/tools.rst | 243 |
8 files changed, 2273 insertions, 0 deletions
diff --git a/3rdparty/bgfx/docs/bgfx.rst b/3rdparty/bgfx/docs/bgfx.rst new file mode 100644 index 00000000000..911a7fb6f79 --- /dev/null +++ b/3rdparty/bgfx/docs/bgfx.rst @@ -0,0 +1,605 @@ +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: + + - `Hello, bgfx! <https://dev.to/pperon/hello-bgfx-4dka>`_ + - `bgfx-minimal-example <https://github.com/jpcy/bgfx-minimal-example#bgfx-minimal-example>`_ + - `Using the bgfx library with C++ on Ubuntu <https://www.sandeepnambiar.com/getting-started-with-bgfx/>`_ + +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_APPLE +.. doxygendefine:: BGFX_PCI_ID_INTEL +.. doxygendefine:: BGFX_PCI_ID_NVIDIA +.. doxygendefine:: BGFX_PCI_ID_MICROSOFT + +.. 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_DRAW_INDIRECT_COUNT +.. 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 +----- + +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. + +.. 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 +******* + +If the Scissor rectangle needs to be changed for +every draw call in a View, use `bgfx::setScissor`. +Otherwise, use `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 +****** + +In Views, 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) +.. doxygenfunction:: bgfx::submit(ViewId _id, ProgramHandle _program, IndirectBufferHandle _indirectHandle, uint16_t _start, IndexBufferHandle _numHandle, uint32_t _numIndex = 0, uint16_t _numMax = UINT16_MAX, uint32_t _depth = 0, uint8_t _flags = BGFX_DISCARD_ALL) + + +Compute +~~~~~~~ + +Compute state is not preserved between compute dispatches; all state is cleared after calling `bgfx::dispatch`. + +Buffers +******* + +.. 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 +******** + +In Views, all draw commands are executed **after** blit and compute 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 +~~~~ + +In Views, all draw commands are executed **after** blit and compute 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 +~~~~~~~~~~~~~ + +.. doxygenstruct:: bgfx::Attachment + :members: + +.. doxygenfunction:: bgfx::isFrameBufferValid + +.. 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) + +.. 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) diff --git a/3rdparty/bgfx/docs/build.rst b/3rdparty/bgfx/docs/build.rst new file mode 100644 index 00000000000..9f3324a78c4 --- /dev/null +++ b/3rdparty/bgfx/docs/build.rst @@ -0,0 +1,215 @@ +Building +======== + +Dependencies +------------ + +https://github.com/bkaradzic/bx + +https://github.com/bkaradzic/bimg + +Getting Source +-------------- + +:: + + git clone https://github.com/bkaradzic/bx.git + git clone https://github.com/bkaradzic/bimg.git + git clone https://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 Android NDK (r23 or newer): + + - https://developer.android.com/tools/sdk/ndk/index.html + +Set following environment variables: + +:: + + setx ANDROID_NDK_ROOT <path to AndroidNDK directory> + + +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 + +.. note:: **MSYS**, **Cygwin**, etc. shells are not supported! + You must use use **cmd.exe** with provided makefiles. + +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-release64, wasm-debug, wasm-release, osx-debug, osx-release, android-arm64-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's 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 diff --git a/3rdparty/bgfx/docs/examples.rst b/3rdparty/bgfx/docs/examples.rst new file mode 100644 index 00000000000..036f2087e64 --- /dev/null +++ b/3rdparty/bgfx/docs/examples.rst @@ -0,0 +1,706 @@ +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, "&"); + //text = text.replace(/</g, "<"); + //text = text.replace(/>/g, ">"); + //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 maximum 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 programmatically. + ++----------------+------------+------------+--------------------------+-------+----------+ +| 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 + +`47-pixelformats <https://github.com/bkaradzic/bgfx/tree/master/examples/47-pixelformats>`__ +-------------------------------------------------------------------------------------------- + +Pixel Formats + +View and test texture formats + +.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/47-pixelformats/screenshot.png + :alt: example-47-pixelformats + +`48-drawindirect <https://github.com/bkaradzic/bgfx/tree/master/examples/48-drawindirect>`__ +--------------------------------------------------------------------------------------------- + +Draw Indirect + +Simple example of indirect rendering + an implementation of multidraw indirect + +Reference(s): + - `OpenGL MultiDrawIndirect with per-instance textures <https://web.archive.org/web/20201109155619/https://litasa.github.io/blog/2017/09/04/OpenGL-MultiDrawIndirect-with-Individual-Textures>`__. + - `Indirect Rendering - A way to a million draw calls <https://web.archive.org/web/20210926073337/https://cpp-rendering.io/indirect-rendering>`__. + +.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/48-drawindirect/screenshot.png + :alt: example-48-drawindirect + + +`49-hextile <https://github.com/bkaradzic/bgfx/tree/master/examples/49-hextile>`__ +--------------------------------------------------------------------------------------------- + +Realtime Hex-Tiling + +Simple example of how to use Hex-tiling in real time, ported from https://github.com/mmikk/hextile-demo + +Reference(s): + - `Hex-Tiling demo <https://github.com/mmikk/hextile-demo>`__. + - `Paper explaining concepts - <https://github.com/mmikk/mmikk.github.io/blob/master/papers3d/mm_hex_compressed.pdf>`__. + +.. figure:: https://github.com/bkaradzic/bgfx/raw/master/examples/49-hextile/screenshot.png + :alt: example-49-hextile diff --git a/3rdparty/bgfx/docs/index.rst b/3rdparty/bgfx/docs/index.rst new file mode 100644 index 00000000000..8a096171758 --- /dev/null +++ b/3rdparty/bgfx/docs/index.rst @@ -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 diff --git a/3rdparty/bgfx/docs/internals.rst b/3rdparty/bgfx/docs/internals.rst new file mode 100644 index 00000000000..8e71d76eb3e --- /dev/null +++ b/3rdparty/bgfx/docs/internals.rst @@ -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. diff --git a/3rdparty/bgfx/docs/license.rst b/3rdparty/bgfx/docs/license.rst new file mode 100644 index 00000000000..130b994d2ba --- /dev/null +++ b/3rdparty/bgfx/docs/license.rst @@ -0,0 +1,132 @@ +License +======= + +`License (BSD 2-clause) <https://github.com/bkaradzic/bgfx/blob/master/LICENSE>`__ +---------------------------------------------------------------------------------- + +:: + + Copyright 2010-2022 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. + + - cgltf (`MIT <https://github.com/bkaradzic/bgfx/blob/master/3rdparty/cgltf/LICENSE>`__) + - Dear ImGui (`MIT <https://github.com/bkaradzic/bgfx/blob/master/3rdparty/dear-imgui/LICENSE.txt>`__) + - Blendish (`MIT <https://github.com/bkaradzic/bgfx/blob/67b2f1e2bfcf6015db6d8b5c2d6fcfd5cee7e167/examples/20-nanovg/blendish.h#L2-L22>`__) + - fcpp (`BSD <https://github.com/bkaradzic/bgfx/blob/master/3rdparty/fcpp/COPYING>`__) + - glsl-optimizer (`MIT <https://github.com/bkaradzic/bgfx/blob/master/3rdparty/glsl-optimizer/license.txt>`__) + - glslang (`Apache 2.0 <https://github.com/bkaradzic/bgfx/blob/master/3rdparty/glslang/LICENSE.txt>`__) + - IconFontCppHeaders (`MIT <https://github.com/bkaradzic/bgfx/blob/master/3rdparty/iconfontheaders/LICENSE>`__) + - meshoptimizer (`MIT <https://github.com/bkaradzic/bgfx/blob/master/3rdparty/meshoptimizer/LICENSE.md>`__) + - NanoVG (`ZLIB <https://github.com/bkaradzic/bgfx/blob/67b2f1e2bfcf6015db6d8b5c2d6fcfd5cee7e167/examples/common/nanovg/nanovg.cpp#L2-L16>`__) + - SDF (`MIT <https://github.com/bkaradzic/bgfx/blob/master/3rdparty/sdf/LICENSE.txt>`__) + - spirv-cross (`Apache 2.0 <https://github.com/bkaradzic/bgfx/blob/master/3rdparty/spirv-cross/LICENSE>`__) + - spirv-headers (`Khronos/MIT <https://github.com/bkaradzic/bgfx/blob/master/3rdparty/spirv-headers/LICENSE>`__) + - spirv-tools (`Apache 2.0 <https://github.com/bkaradzic/bgfx/blob/master/3rdparty/spirv-tools/LICENSE>`__) + - stb (`Public Domain <https://github.com/bkaradzic/bgfx/blob/master/3rdparty/stb/LICENSE>`__) + +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 + +Hextile example-49 texture (CC0 License) + + - https://polyhaven.com/a/aerial_rocks_04 diff --git a/3rdparty/bgfx/docs/overview.rst b/3rdparty/bgfx/docs/overview.rst new file mode 100644 index 00000000000..ab119e79d69 --- /dev/null +++ b/3rdparty/bgfx/docs/overview.rst @@ -0,0 +1,300 @@ +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) +- FreeBSD +- iOS (iPhone, iPad, AppleTV) +- Linux +- MIPS Creator CI20 +- OSX (10.12+) +- PlayStation 4 +- RaspberryPi +- UWP (Universal Windows, Xbox One) +- Wasm/Emscripten +- Windows (XP, Vista, 7, 8, 10) + +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>`__ +- `Beef API bindings <https://github.com/bkaradzic/bgfx/tree/master/bindings/bf>`__ +- `C# language API bindings #1 <https://github.com/bkaradzic/bgfx/tree/master/bindings/cs>`__ +- `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>`__ +- `Pascal language API bindings <https://github.com/Akira13641/PasBGFX>`__ +- `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>`__ +- `Zig language API bindings <https://github.com/bkaradzic/bgfx/tree/master/bindings/zig>`__ + + +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 running 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. + - Sandy Carter (`@bwrsandman <https://github.com/bwrsandman>`__) - `47-pixelformats + <examples.html#pixelformats>`__ example, and various fixes and improvements. + - Liam Twigger (`@SnapperTT <https://github.com/SnapperTT>`__) - `48-drawindirect <examples.html#drawindirect>`__ example. + - Preetish Kakkar (`@blackhole <https://github.com/preetishkakkar>`__) - `49-hextile <examples.html#49-hextile>`__ example. + - Biswapriyo Nath (`@Biswa96 <https://github.com/Biswa96>`__) - GitHub Actions CI. + - Raziel Alphadios (`@RazielXYZ <https://github.com/RazielXYZ>`__) - Various fixes and improvements. + +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> diff --git a/3rdparty/bgfx/docs/tools.rst b/3rdparty/bgfx/docs/tools.rst new file mode 100644 index 00000000000..9dc667a872a --- /dev/null +++ b/3rdparty/bgfx/docs/tools.rst @@ -0,0 +1,243 @@ +Tools +===== + +Geometry Compiler (geometryc) +----------------------------- + +Converts Wavefront .obj, or glTF 2.0 mesh files to a format which is optimized for use 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 Display this help and exit. + -v, --version Output version information and exit. + -f <file path> Input's file path. + -o <file path> Output's 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. + | Defaults to 17. + | Less steps = less precise OBB. + | 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. Defaults to '--lh-up+y' — Left-Handed +Y is up. + +Geometry Viewer (geometryv) +--------------------------- + +A geometry viewer. + +Shader Compiler (shaderc) +------------------------- + +Shader Compiler is used to compile bgfx's cross-platform shader language, which based on GLSL. +It uses an ANSI C pre-processor to transform the GLSL-like language into HLSL. +This method has certain drawbacks, +but overall it's simple and allows for quick authoring of cross-platform shaders. + +Some differences between bgfx's shaderc flavor of GLSL and vanilla GLSL: + +- ``bool/int`` uniforms are not allowed; all uniforms must be ``float``. +- Attributes and varyings can only be accessed from ``main()``. +- ``SAMPLER2D/3D/CUBE/etc.`` macros replace the ``sampler2D/3D/Cube/etc.`` tokens. +- ``vec2/3/4_splat(<value>)`` replaces the ``vec2/3/4(<value>)`` constructor. + ``vec2/3/4`` constructors with multiple values are still valid. +- ``mtxFromCols/mtxFromRows`` must be used for constructing matrices. +- ``mul(x, y)`` must be used when multiplying vectors with matrices. +- A ``varying.def.sc`` file must be used to define input/output semantics and types, + instead of using ``attribute/in`` and ``varying/in/out``. + This file cannot include comments, and typically only one is necessary. +- ``$input/$output`` tokens corresponding to inputs and outputs defined in + ``varying.def.sc`` must be used at the beginning of shader. + +Defines +~~~~~~~ + +Shader Compiler also has the following default defines (default value is set to 0): + + =============================== ======================= ======================================== + Define symbol Description Option + =============================== ======================= ======================================== + ``BX_PLATFORM_ANDROID`` Android platform ``--platform android`` + ``BX_PLATFORM_EMSCRIPTEN`` Emscripten platform ``--platform asm.js`` + ``BX_PLATFORM_IOS`` iOS platform ``--platform ios`` + ``BX_PLATFORM_LINUX`` Linux platform ``--platform linux`` + ``BX_PLATFORM_OSX`` macOS platform ``--platform osx`` + ``BX_PLATFORM_PS4`` PlayStation 4 platform ``--platform orbis`` + ``BX_PLATFORM_WINDOWS`` Windows platform ``--platform windows`` + ``BX_PLATFORM_XBOXONE`` *Not implemented* + ------------------------------- ----------------------- ---------------------------------------- + ``BGFX_SHADER_LANGUAGE_GLSL`` GLSL profile ``-p NNN`` and ``-p NNN_es`` + ``BGFX_SHADER_LANGUAGE_HLSL`` HLSL profile ``-p s_N_N`` + ``BGFX_SHADER_LANGUAGE_METAL`` Metal profile ``-p metal`` + ``BGFX_SHADER_LANGUAGE_PSSL`` PSSL profile ``-p pssl`` + ``BGFX_SHADER_LANGUAGE_SPIRV`` SPIR-V profile ``-p spirv`` and ``-p spirvNN-NN`` + ------------------------------- ----------------------- ---------------------------------------- + ``BGFX_SHADER_TYPE_COMPUTE`` Compute shader ``--type compute`` or ``--type c`` + ``BGFX_SHADER_TYPE_FRAGMENT`` Fragment shader ``--type fragment`` or ``--type f`` + ``BGFX_SHADER_TYPE_VERTEX`` Vertex shader ``--type vertex`` or ``--type v`` + =============================== ======================= ======================================== + +Predefined Uniforms +~~~~~~~~~~~~~~~~~~~ + + ======= =================== ==================================================================== + Type Name Description + ======= =================== ==================================================================== + vec4 u_viewRect | View rectangle. + | ``u_viewRect.xy`` - xy offset in screen space. + | ``u_viewRect.zw`` - width/height size in screen space. + vec4 u_viewTexel | Screen-to-texel space conversion. + | ``u_viewTexel.xy = 1.0/u_viewRect.zw;`` + mat4 u_view Transform world-to-view space. + mat4 u_invView Transform view-to-world space. + mat4 u_proj Transform view-to-clip space. + mat4 u_invProj Transform clip-to-view space. + mat4 u_viewProj Transform world-to-clip space. + mat4 u_invViewProj Transform clip-to-world space. + mat4[N] u_model Transform local-to-world space array. + mat4 u_modelView Transform local-to-view space. + mat4 u_modelViewProj Transform local-to-clip space. + float u_alphaRef | The reference value to which incoming alpha + | values are compared. + ======= =================== ==================================================================== + +For more info, see the `shader helper macros +<https://github.com/bkaradzic/bgfx/blob/master/src/bgfx_shader.sh>`__. + +Options: + + -h, --help Display this help and exit. + -v, --version Output version information and exit. + -f <file path> Input's file path. + -i <include path> Include path. (for multiple paths use -i multiple times) + -o <file path> Output's 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. + Defaults to GLSL. + --preprocess Only pre-process. + --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. + Can be 'vertex', 'fragment, or 'compute'. + --varyingdef <file path> A varying.def.sc's file path. + --verbose Be verbose. + +(DX9 and DX11 only): + + --debug Debug information. + --disasm Disassemble a compiled shader. + -O <level> Set optimization level. + Can be 0–3. + --Werror Treat warnings as errors. + +Building shaders +~~~~~~~~~~~~~~~~ + +Shaders can be compiled for all renderers by using the ``shaderc`` tool. +A Makefile to simplify building shaders is provided in the `bgfx examples +<https://github.com/bkaradzic/bgfx/tree/master/examples>`__. +D3D shaders can be only compiled on Windows. + +Texture Compiler (texturec) +--------------------------- + +Convert PNG, TGA, DDS, KTX, and PVR textures 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: + +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 or vertical 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) +------------------------- + +A texture viewer. |