KhronosGroup · MarkCallow · May 14, 2024 · Apr 11, 2024 · May 6, 2024 · May 6, 2024
diff --git a/tools/ktx/CMakeLists.txt b/tools/ktx/CMakeLists.txt
@@ -16,7 +16,9 @@ add_executable(ktxtools
         command_transcode.cpp
         command_validate.cpp
         deflate_utils.h
+        encode_utils_astc.h
         encode_utils_basis.h
+        encode_utils_common.h
         format_descriptor.h
         formats.h
         fragment_uri.h

diff --git a/tools/ktx/command_compare.cpp b/tools/ktx/command_compare.cpp
@@ -831,6 +831,7 @@ Compare two KTX2 files.
     set for UTF-8 you will see incorrect characters in output of the file
     identifier on each side of the "KTX nn".
 
+@section ktx\_compare\_options OPTIONS
     The following options are available:
     @snippet{doc} ktx/command.h command options_format
     <dl>

diff --git a/tools/ktx/command_create.cpp b/tools/ktx/command_create.cpp
@@ -590,13 +590,25 @@ Create a KTX2 file from various input files.
     The number of input-files specified must match the expected number of input images
     based on the used options.
 
-    The following options are available:
+@section ktx\_create\_options OPTIONS
+  @subsection ktx\_create\_options\_general General Options
+    The following are available:
     <dl>
         <dt>\--format &lt;enum&gt;</dt>
-        <dd>KTX format enum that specifies the image data format.
+        <dd>KTX format enum that specifies the data format of the images in the created texture.
             The enum names are matching the VkFormats without the VK_FORMAT_ prefix.
-            The VK_FORMAT_ prefix is ignored if present.<br />
-            When used with --encode it specifies the target format before the encoding step.
+            The VK_FORMAT_ prefix is ignored if present. Case insensitive. Required.<br />
+            <br />
+            If the format is an ASTC format a texture object with the target format
+            @c R8G8B8_{SRGB,UNORM} or  @c R8G8B8A8_{SRGB,UNORM} is created
+            then encoded to the specified ASTC format. The latter format is chosen if alpha
+            is present in the input. @c SRGB or @c UNORM is chosen depending on the
+            specified ASTC format. The ASTC-specific and common encoder options listed
+            @ref ktx_create_options_encoding "below" become valid, otherwise they are ignored.
+            <!--This matches the functionality of the @ref ktx_encode "ktx encode" command
+            when an ASTC format is specified.<br /> -->
+            <br />
+            When used with @b \--encode it specifies the target format before the encoding step.
             In this case it must be one of:
             <ul>
                 <li>R8_UNORM</li>
@@ -608,11 +620,17 @@ Create a KTX2 file from various input files.
                 <li>R8G8B8A8_UNORM</li>
                 <li>R8G8B8A8_SRGB</li>
             </ul>
-            If the format is an ASTC format the ASTC encoder specific options become valid,
-            otherwise they are ignored.<br />
-            The format will be used to verify and load all input files into a texture before encoding.<br />
-            Case insensitive. Required.</dd>
-        @snippet{doc} ktx/astc_utils.h command options_encode_astc
+            The format will be used to verify and load all input files into a texture before
+            performing any specified encoding.
+        </dd>
+        <dt>\--encode basis-lz | uastc</dt>
+        <dd>Encode the texture with the specified codec before saving it.
+            This option matches the functionality of the @ref ktx_encode "ktx encode" command.
+            With each choice, the specific and common encoder options listed
+            @ref ktx_create_options_encoding "below"  become valid, otherwise they
+            are ignored. Case-insensitive.</dd>
+
+            @snippet{doc} ktx/encode_utils_basis.h command options_basis_encoders
         <dt>\--1d</dt>
         <dd>Create a 1D texture. If not set the texture will be a 2D or 3D texture.</dd>
         <dt>\--cubemap</dt>
@@ -656,19 +674,6 @@ Create a KTX2 file from various input files.
                 wrap | reflect | clamp.
                 Defaults to clamp.</dd>
         </dl>
-    </dl>
-    <dl>
-        <dt>\--encode basis-lz | uastc</dt>
-        <dd>Encode the texture with the specified codec before saving it.
-            This option matches the functionality of the @ref ktx_encode "ktx encode" command.
-            With each encoding option the following encoder specific options become valid,
-            otherwise they are ignored. Case-insensitive.</dd>
-
-        @snippet{doc} ktx/basis_utils.h command options_encode_basis
-        @snippet{doc} ktx/encode_utils_common.h command options_encode_common
-        @snippet{doc} ktx/metrics_utils.h command options_metrics
-    </dl>
-    <dl>
         <dt>\--swizzle [rgba01]{4}</dt>
         <dd>KTX swizzle metadata.</dd>
         <dt>\--input-swizzle [rgba01]{4}</dt>
@@ -713,6 +718,15 @@ Create a KTX2 file from various input files.
     @snippet{doc} ktx/deflate_utils.h command options_deflate
     @snippet{doc} ktx/command.h command options_generic
 
+  @subsection ktx\_create\_options\_encoding Specific and Common Encoding Options
+    The following are available. Specific options become valid only if their encoder has been
+    selected. Common encoder options become valid when an encoder they apply to has
+    been selected. Otherwise they are ignored.
+    @snippet{doc} ktx/encode_utils_astc.h command options_encode_astc
+    @snippet{doc} ktx/encode_utils_basis.h command options_encode_basis
+    @snippet{doc} ktx/encode_utils_common.h command options_encode_common
+    @snippet{doc} ktx/metrics_utils.h command options_metrics
+
 @section ktx_create_exitstatus EXIT STATUS
     @snippet{doc} ktx/command.h command exitstatus
 
@@ -721,6 +735,11 @@ Create a KTX2 file from various input files.
 @par Version 4.0
  - Initial version
 
+ @par Version 4.4
+ - Reorganize encoding options.
+ - Improve explanation of use of @b \--format with @b \--encode.
+ - Improve explanation of ASTC encoding.
+
 @section ktx_create_author AUTHOR
     - Mátyás Császár [Vader], RasterGrid www.rastergrid.com
     - Daniel Rákos, RasterGrid www.rastergrid.com

diff --git a/tools/ktx/command_deflate.cpp b/tools/ktx/command_deflate.cpp
@@ -50,6 +50,7 @@ Deflate (supercompress) a KTX2 file.
     @b ktx @b deflate cannot be applied to KTX files that have been
     supercompressed with BasisLZ.
 
+@section ktx\_deflate\_options OPTIONS
     The following options are available:
     @snippet{doc} ktx/deflate_utils.h command options_deflate
     <dl>

diff --git a/tools/ktx/command_encode.cpp b/tools/ktx/command_encode.cpp
@@ -39,35 +39,63 @@ Encode a KTX2 file.
     ktx encode [option...] @e input-file @e output-file
 
 @section ktx_encode_description DESCRIPTION
-    @b ktx @b encode can encode the KTX file specified as the @e input-file argument,
-    optionally supercompress the result, and save it as the @e output-file.
+    @b ktx @b encode can encode the KTX file specified as the @e input-file argument
+    to a universal format<!-- or one of the ASTC formats,--> optionally supercompress the result,
+    and save it as the @e output-file.
     If the @e input-file is '-' the file will be read from the stdin.
     If the @e output-path is '-' the output file will be written to the stdout.
-    The input file must be R8, RG8, RGB8 or RGBA8 (or their sRGB variant).
+
+    For universal <!-- and ASTC LDR--> formats, the input file must be R8, R8G8, R8G8B8
+    or R8G8B8A8 (or their sRGB variants).
+
+    <!--For ASTC HDR formats the input file must be TBD (e.g. R16_{,S}FLOAT,
+    R16G16_{,S}FLOAT ...
+-->
     If the input file is invalid the first encountered validation error is displayed
     to the stderr and the command exits with the relevant non-zero status code.
 
+@section ktx\_encode\_options OPTIONS
+  @subsection ktx\_encode\_options\_general General Options
+    <!--Specifying both @e \--codec and @e \--format options is an error.
+-->
     The following options are available:
     <dl>
         <dt>\--codec basis-lz | uastc</dt>
-        <dd>Target codec followed by the codec specific options.
-            With each encoding option the following encoder specific options become valid,
-            otherwise they are ignored. Case-insensitive.</dd>
-
-        @snippet{doc} ktx/basis_utils.h command options_encode_basis
-        @snippet{doc} ktx/encode_utils_common.h command options_encode_common
-        @snippet{doc} ktx/metrics_utils.h command options_metrics
+        <dd>Target codec followed by the codec specific options. With each choice
+            the specific and common encoder options listed
+            @ref ktx\_encode\_options\_encoding "below" become valid, otherwise
+            they are ignored. Case-insensitive.</dd>
+
+            @snippet{doc} ktx/encode_utils_basis.h command options_basis_encoders
+<!--        <dt>\--format</dt>
+        <dd>KTX format enum that specifies the target ASTC format. Non-ASTC
+            formats are invalid. When specified the ASTC-specific and common
+            encoder options listed @ref ktx\_encode\_options\_encoding "below"
+            become valid, otherwise they are ignored.
+-->
     </dl>
     @snippet{doc} ktx/deflate_utils.h command options_deflate
     @snippet{doc} ktx/command.h command options_generic
 
+  @subsection ktx\_encode\_options\_encoding Specific and Common Encoding Options
+    The following specific and common encoder options are available. Specific options
+    become valid only if their encoder has been selected. Common encoder options
+    become valid when an encoder they apply to has been selected. Otherwise they are ignored.
+    <!--@snippet{doc} ktx/encode_utils_astc.h command options_encode_astc-->
+    @snippet{doc} ktx/encode_utils_basis.h command options_encode_basis
+    @snippet{doc} ktx/encode_utils_common.h command options_encode_common
+    @snippet{doc} ktx/metrics_utils.h command options_metrics
+
 @section ktx_encode_exitstatus EXIT STATUS
     @snippet{doc} ktx/command.h command exitstatus
 
 @section ktx_encode_history HISTORY
 
 @par Version 4.0
- - Initial version
+ - Initial version.
+
+ @par Version 4.4
+  - Reorganize encoding options.
 
 @section ktx_encode_author AUTHOR
     - Mátyás Császár [Vader], RasterGrid www.rastergrid.com

diff --git a/tools/ktx/command_extract.cpp b/tools/ktx/command_extract.cpp
@@ -72,6 +72,7 @@ Extract selected images from a KTX2 file.
     - D16_UNORM exported as PNG with luminance (Gray) 16 bit
     - Other Depth/Stencil formats exported as EXR with D/S/DS Half/Float
 
+@section ktx\_extract\_options OPTIONS
     The following options are available:
     <dl>
         <dt>\--transcode &lt;target&gt;</dt>

diff --git a/tools/ktx/command_help.cpp b/tools/ktx/command_help.cpp
@@ -65,7 +65,7 @@ struct OptionsHelp {
 Display help information about the ktx tool.
 
 @section ktx_help_synopsis SYNOPSIS
-    ktx help [option...] @e [command]
+    ktx help [option...] [@e command]
 
 @section ktx_help_description DESCRIPTION
     @b ktx @b help displays the man page of a specific ktx command specified as the @e command
@@ -76,21 +76,19 @@ Display help information about the ktx tool.
     To support custom install locations the tool first tries to use the man files relative to
     the executable and falls back to the system man pages.
 
-    The following options are available:
-    <dl>
-        <dt>command</dt>
-        <dd>Specifies which command's man page will be displayed. If the command option is missing
-        the main ktx tool man page will be displayed. Possible options are: <br />
-            @ref ktx_create "create" <br />
-            @ref ktx_extract "extract" <br />
-            @ref ktx_encode "encode" <br />
-            @ref ktx_transcode "transcode" <br />
-            @ref ktx_info "info" <br />
-            @ref ktx_validate "validate" <br />
-            @ref ktx_compare "compare" <br />
-            @ref ktx_help "help"
-        </dd>
-    </dl>
+    @e command specifies which command's man page will be displayed.
+    If @e command is s missing the main ktx tool man page will be displayed.
+    Possible choices are: <br />
+    -        @ref ktx_create "create" <br />
+    -        @ref ktx_extract "extract" <br />
+    -        @ref ktx_encode "encode" <br />
+    -        @ref ktx_transcode "transcode" <br />
+    -        @ref ktx_info "info" <br />
+    -        @ref ktx_validate "validate" <br />
+    -        @ref ktx_compare "compare" <br />
+    -        @ref ktx_help "help"
+
+@section ktx\_help\_options OPTIONS
     @snippet{doc} ktx/command.h command options_generic
 
 @section ktx_help_exitstatus EXIT STATUS

diff --git a/tools/ktx/command_info.cpp b/tools/ktx/command_info.cpp
@@ -49,6 +49,7 @@ Print information about a KTX2 file.
     set for UTF-8 you will see incorrect characters in output of the file
     identifier on each side of the "KTX nn".
 
+@section ktx\_info\_options OPTIONS
     The following options are available:
     @snippet{doc} ktx/command.h command options_format
     @snippet{doc} ktx/command.h command options_generic

diff --git a/tools/ktx/command_transcode.cpp b/tools/ktx/command_transcode.cpp
@@ -47,6 +47,7 @@ Transcode a KTX2 file.
     If the input file is invalid the first encountered validation error is displayed
     to the stderr and the command exits with the relevant non-zero status code.
 
+@section ktx\_transcode\_options OPTIONS
     The following options are available:
     <dl>
         <dt>\--target &lt;target&gt;</dt>

diff --git a/tools/ktx/command_validate.cpp b/tools/ktx/command_validate.cpp
@@ -40,6 +40,7 @@ Validate a KTX2 file.
     set for UTF-8 you will see incorrect characters in output of the file
     identifier on each side of the "KTX nn".
 
+@section ktx\_validate\_options OPTIONS
     The following options are available:
     @snippet{doc} ktx/command.h command options_format
     <dl>

diff --git a/tools/ktx/encode_utils_astc.h b/tools/ktx/encode_utils_astc.h
@@ -19,9 +19,7 @@ namespace ktx {
     <dt>
         ASTC:
     </dt>
-    <dd>
-        Encode the image data with ASTC compression.
-    </dd>
+    <dd></dd>
 
     <dl>
         <dt>\--astc-quality &lt;level&gt;</dt>
@@ -38,7 +36,7 @@ namespace ktx {
                <tr><td>medium     </td> <td>(equivalent to quality =  60) </td></tr>
                <tr><td>thorough   </td> <td>(equivalent to quality =  98) </td></tr>
                <tr><td>exhaustive </td> <td>(equivalent to quality = 100) </td></tr>
-            /table>
+          </table>
         </dd>
         <dt>\--astc-perceptual</dt>
         <dd>The codec should optimize for perceptual error, instead of
@@ -47,9 +45,6 @@ namespace ktx {
             methods are currently only available for normal maps and RGB
             color data.</dd>
     </dl>
-
-    @snippet{doc} ktx/encode_utils_common.h command options_encode_common
-
 </dl>
 //! [command options_encode_astc]
 */

diff --git a/tools/ktx/encode_utils_basis.h b/tools/ktx/encode_utils_basis.h
@@ -22,19 +22,35 @@ enum class BasisCodec {
 };
 
 /**
-//! [command options_encode_basis]
+//! [command options_basis_encoders]
 <dl>
     <dt>
         basis-lz:
     </dt>
     <dd>
-        Supercompress the image data with ETC1S / BasisLZ.
+        Supercompress the image data with transcodable ETC1S / BasisLZ.
         RED images will become RGB with RED in each component (RRR). RG
         images will have R in the RGB part and G in the alpha part of
         the compressed texture (RRRG). When set, the following BasisLZ-related
         options become valid, otherwise they are ignored.
     </dd>
+    <dt>
+        uastc:
+    </dt>
+    <dd>
+        Create a texture in high-quality transcodable UASTC format.
+    </dd>
+</dl>
+//! [command options_basis_encoders]
+*/
 
+/**
+//! [command options_encode_basis]
+<dl>
+    <dt>
+        basis-lz:
+    </dt>
+    <dd></dd>
     <dl>
         <dt>\--clevel &lt;level&gt;</dt>
              <dd>ETC1S / BasisLZ compression level, an encoding speed vs.
@@ -89,9 +105,7 @@ enum class BasisCodec {
     <dt>
         uastc:
     </dt>
-    <dd>
-        Create a texture in high-quality transcodable UASTC format.
-    </dd>
+    <dd></dd>
 
     <dl>
         <dt>\--uastc-quality &lt;level&gt;</dt>
@@ -143,9 +157,6 @@ enum class BasisCodec {
         <dd>Disable RDO multithreading (slightly higher compression,
             deterministic).</dd>
     </dl>
-
-    @snippet{doc} ktx/encode_utils_common.h command options_encode_common
-
 </dl>
 //! [command options_encode_basis]
 */

diff --git a/tools/ktx/encode_utils_common.h b/tools/ktx/encode_utils_common.h
@@ -16,13 +16,11 @@ namespace ktx {
 
 /**
 //! [command options_encode_common]
+  <dl>
     <dt>
-        common:
+      common:
     </dt>
-    <dd>
-        Common options.
-    </dd>
-
+    <dd></dd>
     <dl>
         <dt>\--normal-mode</dt>
         <dd>Only valid for linear textures with two or more components.
@@ -51,9 +49,10 @@ namespace ktx {
             returned is 0.</dd>
         <dt>\--no-sse</dt>
         <dd>Forbid use of the SSE instruction set. Ignored if CPU does
-            not support SSE. SSE can only be disabled on the basis-lz and
-            uastc compressors. Ignored for other compressors.</dd>
+            not support SSE. SSE can only be disabled for the basis-lz
+            and uastc encoders. Ignored for other encoders..</dd>
     </dl>
+  </dl>
 //! [command options_encode_common]
 */
 struct OptionsEncodeCommon {