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: Бранимир Караџић <[email protected]>

docs/bgfx.rst

@@ -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'.
+
+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 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`.
+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`.
 
-View state is preserved between multiple frames.
+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)

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

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 <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.
-
-Some differences between bgfx's shaderc flavor of GLSL and regular GLSL:
-
--  No ``bool/int`` uniforms, all uniforms must be ``float``.
--  Attributes and varyings can be accessed only from ``main()``
-   function.
--  Must use ``SAMPLER2D/3D/CUBE/etc.`` macros instead of
-   ``sampler2D/3D/Cube/etc.`` tokens.
--  Must use ``vec2/3/4_splat(<value>)`` instead of
-   ``vec2/3/4(<value>)``.
--  Must use ``mtxFromCols/mtxFromRows`` when constructing matrices in shaders.
--  Must use ``mul(x, y)`` when multiplying vectors and matrices.
--  Must use ``varying.def.sc`` to define input/output semantic and
-   precission instead of using ``attribute/in`` and ``varying/in/out``.
--  ``$input/$output`` tokens must appear at the begining of shader.
-
-For more info see `shader helper
-macros <https://github.com/bkaradzic/bgfx/blob/master/src/bgfx_shader.sh>`__.
+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 begining of shader.
+
+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.
+
+  -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>     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.
+  --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.
 
-Options (DX9 and DX11 only):
+(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.

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 <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"

tools/shaderc/shaderc.cpp

@@ -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"