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

Documentation update 2 (#2756) 

* Reworded & reformatted bgfx.rst for better clarity

* Reworded for clarity; made option format more consistent

* Added one character!

* Updated shaderc help

Will update docs to 100% match soon

* Updated geometryc's help

Co-authored-by: Бранимир Караџић <branimirkaradzic@gmail.com>
This commit is contained in:
ichordev 2022-04-05 05:57:00 +10:00 committed by GitHub
parent 11ba8de2d1
commit 7a5fec1580
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 149 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
docs/bgfx.rst
View File

@ -3,11 +3,12 @@ API Reference
.. note::
TL;DR for simple walkthrough how to use bgfx API, see `Hello, bgfx! <https://dev.to/pperon/hello-bgfx-4dka>`__,
`bgfx-minimal-example <https://github.com/jpcy/bgfx-minimal-example#bgfx-minimal-example>`__,
or `Using the bgfx library with C++ on Ubuntu <https://www.sandeepnambiar.com/getting-started-with-bgfx/>`__
tutorial.
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
-------
@ -158,8 +159,8 @@ Statistics
Platform specific
~~~~~~~~~~~~~~~~~
These are platform specific APIs. It is only necessary to use these APIs in conjunction with
creating windows.
These are platform specific APIs.
It is only necessary to use these APIs in conjunction with creating windows.
.. doxygenfunction:: bgfx::renderFrame
@ -206,19 +207,21 @@ Miscellaneous
Views
-----
View is primary sorting mechanism in bgfx. View represent bucket of draw and compute calls. Compute
and draw calls inside bucket are sorted in the way that all compute calls are executed before draw
calls. Compute calls are always in order of submission, while draw calls are sorted by internal
state if view is not in sequential mode. In the most of cases when z-buffer is used this change in
order is not noticable to desired output. In cases where order has to be preserved (for example in
rendering GUIs), view can be set to be in sequential order. Sequential order is less efficient,
because it doesn't allow state change optimization, and should be avoided when possible.
Views are the primary sorting mechanism in bgfx.
They represent buckets of draw and compute calls, or what are often known as 'passes'.
By default views ids are sorted in ascending order. For dynamic renderers where order might not be
known until the last moment, view ids can be remaped to arbitrary order by calling
`bgfx::setViewOrder`.
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.
View state is preserved between multiple frames.
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)
@ -253,8 +256,8 @@ API for multi-threaded submission.
Draw
~~~~
Draw state is not preserved between two draw calls. All state is cleared after calling
`bgfx::submit`.
Draw state is not preserved between two draw calls.
All state is cleared after calling `bgfx::submit`.
State
*****
@ -351,8 +354,9 @@ Stencil Flags
Scissor
*******
When scissor rectangle is changing per draw call inside the same view use `bgfx::setScissor`,
otherwise prefer `bgfx::setViewScissor`.
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)
@ -413,7 +417,7 @@ Textures
Submit
******
Within view all draw commands are executed after blit and compute commands.
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)
@ -422,8 +426,7 @@ Within view all draw commands are executed after blit and compute commands.
Compute
~~~~~~~
Compute state is not preserved between two compute dispatches. All state is cleared after calling
`bgfx::dispatch`.
Compute state is not preserved between compute dispatches; all state is cleared after calling `bgfx::dispatch`.
Buffers
*******
@ -445,7 +448,7 @@ Images
Dispatch
********
Within view all compute commands are dispatched after blit commands, and before draw commands.
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)
@ -453,7 +456,7 @@ Within view all compute commands are dispatched after blit commands, and before
Blit
~~~~
Within view all blit commands are executed before compute, and draw commands.
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)

2
docs/build.rst
View File

@ -210,7 +210,7 @@ https://github.com/floooh/fips#fips
**Conan** package
https://github.com/firefalcom/bgfx-conan
Minimal example without bgfx' example harness
Minimal example without bgfx's example harness
---------------------------------------------
This project demonstrates minimal amount of code needed to integrate bgfx with GLFW, but without

167
docs/tools.rst
View File

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

23
tools/geometryc/geometryc.cpp
View File

@ -947,26 +947,27 @@ void help(const char* _error = NULL)
"\n"
"Options:\n"
" -h, --help Help.\n"
" -v, --version Version information only.\n"
" -f <file path> Input file path.\n"
" -o <file path> Output file path.\n"
" -h, --help Display this help and exit.\n"
" -v, --version Output version information and exit.\n"
" -f <file path> Input's file path.\n"
" -o <file path> Output's file path.\n"
" -s, --scale <num> Scale factor.\n"
" --ccw Front face is counter-clockwise winding order.\n"
" --flipv Flip texture coordinate V.\n"
" --obb <num> Number of steps for calculating oriented bounding box.\n"
" Default value is 17. Less steps less precise OBB is.\n"
" More steps slower calculation.\n"
" Defaults to 17.\n
" Less steps = less precise OBB.\n"
" More steps = slower calculation.\n"
" --packnormal <num> Normal packing.\n"
" 0 - unpacked 12 bytes (default).\n"
" 0 - unpacked 12 bytes. (default)\n"
" 1 - packed 4 bytes.\n"
" --packuv <num> Texture coordinate packing.\n"
" 0 - unpacked 8 bytes (default).\n"
" 0 - unpacked 8 bytes. (default)\n"
" 1 - packed 4 bytes.\n"
" --tangent Calculate tangent vectors (packing mode is the same as normal).\n"
" --barycentric Adds barycentric vertex attribute (packed in bgfx::Attrib::Color1).\n"
" --tangent Calculate tangent vectors. (packing mode is the same as normal)\n"
" --barycentric Adds barycentric vertex attribute. (Packed in bgfx::Attrib::Color1)\n"
" -c, --compress Compress indices.\n"
" --[l/r]h-up+[y/z] Coordinate system. Default is '--lh-up+y' Left-Handed +Y is up.\n"
" --[l/r]h-up+[y/z] Coordinate system. Defaults to '--lh-up+y' — Left-Handed +Y is up.\n"
"\n"
"For additional information, see https://github.com/bkaradzic/bgfx\n"

28
tools/shaderc/shaderc.cpp
View File

@ -1002,11 +1002,11 @@ namespace bgfx
"\n"
"Options:\n"
" -h, --help Help.\n"
" -v, --version Version information only.\n"
" -f <file path> Input file path.\n"
" -i <include path> Include path (for multiple paths use -i multiple times).\n"
" -o <file path> Output file path.\n"
" -h, --help Display this help and exit.\n"
" -v, --version Output version information and exit.\n"
" -f <file path> Input's file path.\n"
" -i <include path> Include path. (for multiple paths use -i multiple times)\n"
" -o <file path> Output's file path.\n"
" --stdout Output to console.\n"
" --bin2c [array name] Generate C header file. If array name is not specified base file name will be used as name.\n"
" --depends Generate makefile style depends file.\n"
@ -1018,7 +1018,7 @@ namespace bgfx
" orbis\n"
" osx\n"
" windows\n"
" -p, --profile <profile> Shader model (default GLSL).\n"
" -p, --profile <profile> Shader model. Defaults to GLSL.\n"
);
{
@ -1041,20 +1041,20 @@ namespace bgfx
}
bx::printf(
" --preprocess Preprocess only.\n"
" --define <defines> Add defines to preprocessor (semicolon separated).\n"
" --raw Do not process shader. No preprocessor, and no glsl-optimizer (GLSL only).\n"
" --type <type> Shader type (vertex, fragment, compute)\n"
" --varyingdef <file path> Path to varying.def.sc file.\n"
" --verbose Verbose.\n"
" --preprocess Only pre-process.\n"
" --define <defines> Add defines to preprocessor. (Semicolon-separated)\n"
" --raw Do not process shader. No preprocessor, and no glsl-optimizer. (GLSL only)\n"
" --type <type> Shader type. Can be 'vertex', 'fragment, or 'compute'.\n"
" --varyingdef <file path> varying.def.sc's file path.\n"
" --verbose Be verbose.\n"
"\n"
"Options (DX9 and DX11 only):\n"
"(DX9 and DX11 only):\n"
"\n"
" --debug Debug information.\n"
" --disasm Disassemble compiled shader.\n"
" -O <level> Optimization level (0, 1, 2, 3).\n"
" -O <level> Set optimization level. Can be 0 to 3.\n"
" --Werror Treat warnings as errors.\n"
"\n"