diff --git a/src/tzsl_info.hpp b/src/shaders_documentation.hpp similarity index 86% rename from src/tzsl_info.hpp rename to src/shaders_documentation.hpp index 39d2aaa70e..59c64e08d6 100644 --- a/src/tzsl_info.hpp +++ b/src/shaders_documentation.hpp @@ -1,5 +1,6 @@ /** - * @page tzsl Topaz Shader Language + * @page shaders Shaders + * @section tzsl Topaz Shader Language * @section Introduction * TZSL is a high-level shading language with a syntax very similar to the OpenGL Shading Language (GLSL). While GLSL has slightly different dialects for different render APIs (such as OpenGL and Vulkan), TZSL shaders can be used for all render-API builds. * @@ -93,6 +94,7 @@ * * Note: The example above is actually ill-formed -- An image and buffer resource are specified, but they share the same id which is impossible; a resource is either a buffer or an image resource, never both. * @section bif Built-in Functions + * @subsection bif_printf tz_printf * `void tz_printf(fmt: string-literal, ...)` * @note This is only available for Vulkan Debug builds. Otherwise, compiles down to no-op. * @@ -106,17 +108,13 @@ *
  • In the 'Event Browser', navigate to the draw call that invokes the shader.
  • *
  • You should see 'X msg(s)' annotated on the draw call. Click on this to see each printf invocation.
  • * - * @subsection tz_printf_params Parameters - * @subsubsection debug_printf_fmt_str fmt - * String-literal specifying how to interpret the data. Regarding scalar types, format modifiers match that of C's `printf` function. However, format modifiers also exist for the built-in GLSL vector types. - * - * Format for specifier is "%"precision - * - * Format for vector specifier is "%"precision"v" [2, 3, 4] [specifiers above] - * - * @subsubsection debug_printf_fmt_varargs ... - * Arguments specifying data to print. There must be an entry for each format modifier within the format string. Like `printf`, if no modifiers were specified in the format string, this parameter can be omitted. - * @subsection debug_printf_example Examples + * @subsubsection tz_printf_params Parameters + * The parameters are much like C `printf`: + * - String-literal specifying how to interpret the data. Regarding scalar types, format modifiers match that of C's `printf` function. However, format modifiers also exist for the built-in GLSL vector types. + * - Format for specifier is "%"precision + * - Format for vector specifier is "%"precision"v" [2, 3, 4] [specifiers above] + * - Arguments specifying data to print. There must be an entry for each format modifier within the format string. Like `printf`, if no modifiers were specified in the format string, this parameter can be omitted. + * @subsubsection debug_printf_example Examples * Here are a few example usages: * ```c * float myfloat = 3.1415f; diff --git a/src/tools_documentation.hpp b/src/tools_documentation.hpp deleted file mode 100644 index eef36ce5bf..0000000000 --- a/src/tools_documentation.hpp +++ /dev/null @@ -1,63 +0,0 @@ -/** - * @page tools Tools - * This page describes all internal tools used in the Topaz engine. - * - * @section TZSLC TZSLC -- Topaz Shader Language Compiler - * TZSLC is a tool which transpiles .tzsl shaders to produce output files appropriate for various render-api GLSL dialects. - * - In a Vulkan environment, TZSLC produces SPIR-V binaries. - * - In an OpenGL environment, TZSLC produces GLSL sources. - * - * TZSLC is available under the CMake target `tzslc`. It has no additional documentation. - * @subsection TZSL - * Information on the shading language TZSL can be found at: @ref tzsl - * @subsection Usage TZSLC Usage - * `tzslc [-m{module-name}]...` - * - * @subsubsection tzslc_modules Usage -- Modules - * You can pass zero or more modules to TZSLC. TZSLC will not preprocess valid .tzsl syntax unless the corresponding module is passed. - * For example, the module to preprocess image samplers would be called 'sampler', so the tzslc runtime flags would include `-msampler`. - * - * Note that `-mall` is a pseudo-module which causes TZSLC to use all available modules. - * - * But what's the purpose of TZSLC? Why not just use .glsl shaders and be done with it? - *
    - * @subsection problem1 Problem: Using an image sampler within a .glsl shader - * GLSL is somewhat flexible -- Render-apis tend to have their own dialect of GLSL which they use. This means that while often .glsl shaders can be used, for example, both OpenGL and Vulkan - It is not guaranteed to be the case. - * - * TZSLC exists to provide new syntax which preprocesses down to the desired render-api dialect. Consider the following GLSL code to declare a uniform sampler2D: - * @subsubsection VK Vulkan GLSL - * `layout(binding = 1) uniform sampler2D tex_sampler;` - * @subsubsection OGL OpenGL GLSL - * `layout(location = 1) uniform sampler2D tex_sampler;` - * @subsection solution1 Solution: Using a .tzsl shader - * @subsubsection TZSL Topaz TZSL - * `tz_sampler2D_uniform(1) tex_sampler;` - * - * Correctly resolves to either of the two outputs above, depending on the build config used to build the given TZSLC process. - *
    - * @subsection problem2 Problem: Different behaviour between OpenGL/Vulkan - * Sometimes in shaders you may have functionality for a specific render-api but there is no common behaviour provided by TZSL. For example, Vulkan and OpenGL texture-coordinates are slightly different. You might want code which transforms the texture-coordinates to another format only if on Vulkan. - * - * Unfortunately in GLSL there are no magic defines telling you which render-api will be building the shader. - * @subsection solution2 Solution: Vulkan-only or OpenGL-only code fragments - * Fortunately, when building with TZSLC such defines are injected into the code while transpiling to GLSL. - * @subsubsection TZSL Topaz TZSL - * ```c - * layout(location = 0) in vec2 texcoord; - * layout(location = 0) out vec4 output_colour; - * - * void main() - * { - * vec2 texcoord_transformed = texcoord; - * // Assume texcoord is in OpenGL format. If we're on Vulkan, we need to transform it or the image will be 90 degrees off. - * - * #if TZ_VULKAN - * texcoord_transformed.y = 1.0 - texcoord_transformed.y; - * #endif - * - * // Now identical output for both render-apis. - * output_colour = texture(tex_sampler, texcoord_transformed); - * } - * ``` - * - */ \ No newline at end of file