From 7a5fec15802e9d188ac979e642aed16c81cdf953 Mon Sep 17 00:00:00 2001 From: ichordev <15670465+ichordev@users.noreply.github.com> Date: Tue, 5 Apr 2022 05:57:00 +1000 Subject: [PATCH] Documentation update 2 (#2756) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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: Бранимир Караџић --- docs/bgfx.rst | 57 ++++++------ docs/build.rst | 2 +- docs/tools.rst | 167 +++++++++++++++++++--------------- tools/geometryc/geometryc.cpp | 23 ++--- tools/shaderc/shaderc.cpp | 28 +++--- 5 files changed, 149 insertions(+), 128 deletions(-) diff --git a/docs/bgfx.rst b/docs/bgfx.rst index 85be27906..ad6355de0 100644 --- a/docs/bgfx.rst +++ b/docs/bgfx.rst @@ -3,11 +3,12 @@ API Reference .. note:: - - TL;DR for simple walkthrough how to use bgfx API, see `Hello, bgfx! `__, - `bgfx-minimal-example `__, - or `Using the bgfx library with C++ on Ubuntu `__ - 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! `_ + - `bgfx-minimal-example `_ + - `Using the bgfx library with C++ on Ubuntu `_ 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) diff --git a/docs/build.rst b/docs/build.rst index 0524b3e06..583e8fc3e 100644 --- a/docs/build.rst +++ b/docs/build.rst @@ -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 diff --git a/docs/tools.rst b/docs/tools.rst index 23138a1a2..043c3f3db 100644 --- a/docs/tools.rst +++ b/docs/tools.rst @@ -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 Input file path. -o Output file path. -s, --scale Scale factor. --ccw Front face is counter-clockwise winding order. --flipv Flip texture coordinate V. --obb Number of steps for calculating oriented bounding box. - Default value is 17. Less steps less precise OBB is. - More steps slower calculation. - --packnormal Normal packing. - 0 - unpacked 12 bytes (default). + + Defaults to 17. + + Less steps = less precise OBB. + + More steps = slower calculation. + --packnormal Normal packing. + 0 - unpacked 12 bytes. (default) 1 - packed 4 bytes. --packuv 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()`` instead of - ``vec2/3/4()``. -- 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()`` replaces the ``vec2/3/4()`` 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 `__. +For more info, see the `shader helper macros +`__. Options: - -h, --help Help. - -v, --version Version information only. - -f Input file path. - -i Include path (for multiple paths use -i multiple times). - -o Output file path. - --bin2c 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 Target platform. - -p, --profile Shader model (default GLSL). - --preprocess Preprocess only. - --define Add defines to preprocessor (semicolon separated). - --raw Do not process shader. No preprocessor, and no glsl-optimizer (GLSL only). - --type Shader type (vertex, fragment, compute) - --varyingdef 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 The input's file path. + -i Include path. (for multiple paths use -i multiple times) + -o The output's file path. + --bin2c 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 Set target platform. + -p, --profile Shader model. + + Defaults to GLSL. + --preprocess Only pre-process. + --define Add defines to preprocessor. (semicolon separated) + --raw Do not process shader. No preprocessor, and no glsl-optimizer. (GLSL only) + --type Shader type. + + Can be 'vertex', 'fragment, or 'compute'. + --varyingdef A varying.def.sc's file path. + --verbose Be verbose. + +(DX9 and DX11 only): --debug Debug information. - --disasm Disassemble compiled shader. - -O Optimization level (0, 1, 2, 3). - --Werror Treat warnings as errors. + --disasm Disassemble a compiled shader. + -O 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 +`__. +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 Input file path. - -o Output file path. - -t Output format type (BC1/2/3/4/5, ETC1, PVR14, etc.). - -q Encoding quality (default, fastest, highest). - -m, --mips Generate mip-maps. - --mipskip Skip 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 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 Maximum width/height (image will be scaled down and aspect ratio will be preserved). - --radiance Radiance cubemap filter. (Lighting model: Phong, PhongBrdf, Blinn, BlinnBrdf, GGX) - --as 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 Input file path. + -o Output file path. + -t Output format type. (BC1/2/3/4/5, ETC1, PVR14, etc.) + -q Encoding quality. + + Can be 'default', 'fastest', or 'highest'. + -m, --mips Generate mip-maps. + --mipskip Skip 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 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 Maximum width/height. (Image will be scaled down and aspect ratio will be preserved) + --radiance Radiance cubemap filter. + + Model can be 'Phong', 'PhongBrdf', 'Blinn', 'BlinnBrdf', or 'GGX'. + --as 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. diff --git a/tools/geometryc/geometryc.cpp b/tools/geometryc/geometryc.cpp index a037283fa..030ba9df5 100644 --- a/tools/geometryc/geometryc.cpp +++ b/tools/geometryc/geometryc.cpp @@ -947,26 +947,27 @@ void help(const char* _error = NULL) "\n" "Options:\n" - " -h, --help Help.\n" - " -v, --version Version information only.\n" - " -f Input file path.\n" - " -o Output file path.\n" + " -h, --help Display this help and exit.\n" + " -v, --version Output version information and exit.\n" + " -f Input's file path.\n" + " -o Output's file path.\n" " -s, --scale Scale factor.\n" " --ccw Front face is counter-clockwise winding order.\n" " --flipv Flip texture coordinate V.\n" " --obb 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 Normal packing.\n" - " 0 - unpacked 12 bytes (default).\n" + " 0 - unpacked 12 bytes. (default)\n" " 1 - packed 4 bytes.\n" " --packuv 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" diff --git a/tools/shaderc/shaderc.cpp b/tools/shaderc/shaderc.cpp index 536ef0d78..a8c284c14 100644 --- a/tools/shaderc/shaderc.cpp +++ b/tools/shaderc/shaderc.cpp @@ -1002,11 +1002,11 @@ namespace bgfx "\n" "Options:\n" - " -h, --help Help.\n" - " -v, --version Version information only.\n" - " -f Input file path.\n" - " -i Include path (for multiple paths use -i multiple times).\n" - " -o Output file path.\n" + " -h, --help Display this help and exit.\n" + " -v, --version Output version information and exit.\n" + " -f Input's file path.\n" + " -i Include path. (for multiple paths use -i multiple times)\n" + " -o 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 Shader model (default GLSL).\n" + " -p, --profile Shader model. Defaults to GLSL.\n" ); { @@ -1041,20 +1041,20 @@ namespace bgfx } bx::printf( - " --preprocess Preprocess only.\n" - " --define Add defines to preprocessor (semicolon separated).\n" - " --raw Do not process shader. No preprocessor, and no glsl-optimizer (GLSL only).\n" - " --type Shader type (vertex, fragment, compute)\n" - " --varyingdef Path to varying.def.sc file.\n" - " --verbose Verbose.\n" + " --preprocess Only pre-process.\n" + " --define Add defines to preprocessor. (Semicolon-separated)\n" + " --raw Do not process shader. No preprocessor, and no glsl-optimizer. (GLSL only)\n" + " --type Shader type. Can be 'vertex', 'fragment, or 'compute'.\n" + " --varyingdef 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 Optimization level (0, 1, 2, 3).\n" + " -O Set optimization level. Can be 0 to 3.\n" " --Werror Treat warnings as errors.\n" "\n"