diff --git a/docs/tools.rst b/docs/tools.rst index 366dd7b65..9dc667a87 100644 --- a/docs/tools.rst +++ b/docs/tools.rst @@ -27,23 +27,30 @@ Options: -f Input's file path. -o Output's 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. - Defaults to 17. - Less steps = less precise OBB. + --ccw Front face is counter-clockwise winding order. + + --flipv Flip texture coordinate V. + + --obb | Number of steps for calculating oriented bounding box. + | 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) + | 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) - 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) - 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) @@ -74,11 +81,14 @@ Some differences between bgfx's shaderc flavor of GLSL and vanilla GLSL: - ``$input/$output`` tokens corresponding to inputs and outputs defined in ``varying.def.sc`` must be used at the beginning of shader. -Shader Compiler also has the following default defines: +Defines +~~~~~~~ - =============================== ======================= ======= - Define symbol Description Option - =============================== ======================= ======= +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`` @@ -87,17 +97,41 @@ Shader Compiler also has the following default defines: ``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 `__. @@ -113,12 +147,12 @@ Options: --depends Generate makefile style depends file. --platform Target platform. -p, --profile Shader model. - Defaults to GLSL. + 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'. + Can be 'vertex', 'fragment, or 'compute'. --varyingdef A varying.def.sc's file path. --verbose Be verbose. @@ -127,8 +161,8 @@ Options: --debug Debug information. --disasm Disassemble a compiled shader. -O Set optimization level. - Can be 0–3. - --Werror Treat warnings as errors. + Can be 0–3. + --Werror Treat warnings as errors. Building shaders ~~~~~~~~~~~~~~~~ @@ -167,29 +201,41 @@ Supported file formats: Options: - -h, --help Display this help and exit. - -v, --version Output version information and exit. - -f Input's file path. - -o Output's 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. +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 or vertical 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. Texture Viewer (texturev) -------------------------