Diligent Tools

repository·master·Indexed 41 days ago

https://github.com/diligentgraphics/diligenttools

A collection of utility libraries for the Diligent Engine, featuring a GLTF 2.0 asset loader with Draco compression support, ImGui integration, and a texture loader for jpg, png, tiff, dds, and ktx formats. It includes the Render State Packager for processing Diligent Render State Notation (DRSN) files into optimized archives and the HLSL2GLSLConverter for offline shader translation.

Tokens
7.7K
Snippets
20
Records
29
Agent score
51%

What's inside Diligent Tools

  1. Overview of Diligent Tools libraries

    master

    Diligent Tools provides additional functionality built on top of the Diligent Engine core module. It includes several specialized libraries for graphics development:

    • Texture loader: Supports loading jpg, png, tiff, dds, and ktx formats.
    • Asset Loader: Supports GLTF 2.0 assets.
    • Imgui: An implementation of dear imgui integrated with the Diligent API.
    • NativeApp: Provides native application implementations for supported platforms.
    • HLSL2GLSLConverter: An offline utility for converting HLSL to GLSL.
    • RenderStateNotation: A library for parsing Diligent Render State notation.
    • RenderStatePackager: A tool for packaging render states.
  2. Understand Diligent Render State Notation (DRSN)

    master

    DRSN is a JSON-based format used to describe render states. A DRSN file is composed of three primary sections:

    1. Shaders: Defines shader stages, source files, entry points, and macros.
    2. ResourceSignatures: Contains descriptions of pipeline resource signatures (e.g., constant buffers, samplers).
    3. Pipelines: Describes pipeline states (PSOs), including graphics/compute settings and links to shaders and signatures.

    Important: All shader, signature, and pipeline resource names within an archive must be unique.

    {
        "ResourceSignatures": [
            {
                "Name": "Signature0",
                "Resources": [
                    {
                        "Name": "Constants",
                        "ShaderStages": ["VERTEX", "PIXEL"],
                        "VarType": "DYNAMIC",
                        "ResourceType": "CONSTANT_BUFFER",
                        "Flags": ["NO_DYNAMIC_BUFFERS"]
                    }
                ],
                "ImmutableSamplers": [
                    {
                        "ShaderStages": ["PIXEL"],
                        "SamplerOrTextureName": "LinearSampler",
                        "Desc": {
                            "BorderColor" : [1.0, 1.0, 1.0, 1.0]
                        }
                    }
                ]
            }
        ],
        "Shaders": [
            {
                "Desc": {
                    "Name": "My vertex shader",
                    "ShaderType": "VERTEX"
                },
                "SourceLanguage": "HLSL",
                "FilePath": "VertexShader.vsh",
                "EntryPoint": "VSmain",
                "UseCombinedTextureSamplers": true,
                "Macros": [
                    {"Name": "MY_MACRO_0", "Definition": "0"}
                ]
            }
        ],
        "Pipelines": [
            {
                "PSODesc": {
                    "Name": "My PSO 0",
                    "PipelineType": "GRAPHICS"
                },
                "GraphicsPipeline": {
                    "DepthStencilDesc": {
                        "DepthEnable": false
                    },
                    "InputLayout": {
                        "LayoutElements": [
                            { "NumComponents": 3 },
                            { "InputIndex": 1, "NumComponents": 4 }
                        ]
                    },
                    "NumRenderTargets": 1,
                    "RTVFormats": { "0": "RGBA8_UNORM_SRGB" },
                    "RasterizerDesc": { "CullMode": "FRONT" },
                    "BlendDesc": {
                        "RenderTargets": { "0": { "BlendEnable": true } }
                    }
                },
                "ppResourceSignatures": [ "Signature0" ],
                "pVS": "My vertex shader",
                "pPS": "My pixel shader"
            }
        ]
    }
  3. Use the Defaults section in DRSN

    master

    You can define a Defaults section in your DRSN file to specify common values for Shader, Pipeline, and ResourceSignature objects. This reduces redundancy in the file.

    {
        "Defaults": {
            "Shader": {
                "SourceLanguage": "HLSL",
                "UseCombinedTextureSamplers": true
            },
            "Pipeline": {
                "PSODesc": {
                    "ResourceLayout": {
                        "DefaultVariableType": "MUTABLE"
                    }
                }
            }
        },
        "Pipelines": []
    }
  4. Import DRSN files for shared definitions

    master

    DRSN files support an Imports array, allowing you to share common shader, signature, or pipeline definitions across multiple files. To resolve these imports, use the -r (render_state_dir) command line option to define the search path(s) where the imported files reside.

    // RenderStatesLib.json
    {
        "Imports": [
            "RenderState0.json",
            "RenderState1.json"
        ]
    }
    Diligent-RenderStatePackager.exe -s ./Shaders -r ./RenderStates -i RenderStatesLib.drsn --vulkan
  5. Customize the GLTF loading process

    master

    The Diligent::GLTF::Model loader is highly flexible. You can customize the loading process by configuring the following parameters within the loading setup:

    • Texture attribute configuration: Control how textures are processed.
    • Vertex layout: Define specific vertex formats.
    • Callbacks: Provide custom logic for loading Nodes, Meshes, Primitives, and Materials.
    • GPU resource cache: Manage how GPU resources are cached during the loading process.
  6. Manage JPEG comment (COM) blocks with rdjpgcom and wrjpgcom

    master

    JPEG files can contain COM blocks for user-supplied text (annotations, titles, etc.).

    Read Comments (rdjpgcom):

    • rdjpgcom [-raw] [-verbose] [inputfilename]
    • -raw (-r): Outputs non-printable characters in comments.
    • -verbose (-v): Displays JPEG image dimensions along with comments.

    Write Comments (wrjpgcom):

    • wrjpgcom [switches] [inputfilename] [outputfilename] (Note: On non-Unix, both files must be named).
    • -replace: Deletes any existing COM blocks before adding new ones.
    • -comment "text": Supplies new comment text via command line.
    • -cfile name: Reads new comment text from a specified file.

    Caution: Do not overwrite the input file by redirecting wrjpgcom output back into it; this will destroy your file.

    # Example: Add a comment to a JPEG file
    wrjpgcom -replace -comment "My Annotation" input.jpg output.jpg
    
    # Example: Read comments from a JPEG file
    rdjpgcom -v input.jpg
  7. Use the Diligent GLTF Model loader

    master

    The Asset Loader library provides the Diligent::GLTF::Model class to load and initialize all Diligent Engine objects required to render GLTF 2.0 models. It supports ASCII, Binary, and Embedded GLTF specifications, as well as Draco Mesh Compression (if Draco is included in the project).

    To load a model, create a GLTF::ModelCreateInfo object, specify the file path, and instantiate the GLTF::Model using your device and immediate context pointers.

    GLTF::ModelCreateInfo ModelCI;
    ModelCI.FileName = "MyAsset.gltf";
    
    m_Model = std::make_unique<GLTF::Model>(m_pDevice, m_pImmediateContext, ModelCI);
  8. Compress images to JPEG using cjpeg

    master

    Use the cjpeg program to compress image files (PPM, PGM, BMP, GIF, Targa, or RLE) into JPEG format.

    Command Syntax:

    • Unix-like systems: cjpeg [switches] [imagefile] > jpegfile (writes to stdout).
    • Non-Unix systems: cjpeg [switches] imagefile jpegfile (explicit input/output files).
    • Universal (for scripts): cjpeg [switches] -outfile jpegfile imagefile.

    Key Options:

    • -quality N: Sets quality from 0 (worst) to 100 (best). Default is 75. For optimal results, use values between 50 and 95.
    • -grayscale: Creates a monochrome JPEG. Recommended for grayscale BMP or GIF inputs to reduce file size.
    • -rgb: Creates an RGB JPEG, suppressing conversion to YCbCr.
    • -optimize: Performs entropy encoding optimization. Makes files smaller but uses more memory and time during compression.
    • -progressive: Creates a progressive JPEG, which displays a low-quality version quickly before refining.
    • -scale M/N: Scales the output image by factor M/N.
    # Example: Compress a BMP to JPEG with high quality and optimization
    cjpeg -quality 90 -optimize input.bmp -outfile output.jpg
  9. Enable Draco compression in Asset Loader

    master

    To use Draco compression with the Asset Loader (GLTF 2.0 support), you must include the Draco repository in your project.

    There are two ways to configure this with CMake:

    1. Ensure the Draco source folder is processed by CMake before the DiligentTools folder.
    2. Specify the path to your Draco installation using the DRACO_PATH CMake variable.
    cmake -DDRACO_PATH=/path/to/draco ..
  10. Decompress JPEG files using djpeg

    master

    Use the djpeg program to decompress JPEG files back into conventional image formats (PPM, PGM, BMP, GIF, Targa, or RLE).

    Command Syntax:

    • Unix-like systems: djpeg [switches] [jpegfile] > imagefile.
    • Non-Unix systems: djpeg [switches] jpegfile imagefile.
    • Universal (for scripts): djpeg [switches] -outfile imagefile jpegfile.

    Key Options:

    • -colors N: Reduces the output image to at most N colors (useful for colormapped displays).
    • -fast: Selects recommended options for fast, low-quality output (equivalent to -dct fast -nosmooth -onepass -dither ordered).
    • -grayscale: Forces grayscale output even if the JPEG is color.
    • -rgb: Forces RGB output even if the JPEG is grayscale.
    • -scale M/N: Scales the output image by factor M/N.
    • -bmp, -gif, -pnm, -targa: Selects specific output formats.
    # Example: Decompress a JPEG to a BMP file
    djpeg -outfile output.bmp input.jpg
  11. Perform lossless JPEG transformations with jpegtran

    master

    The jpegtran utility performs transformations on JPEG files by rearranging compressed DCT coefficients without fully decoding the image. This makes transformations like rotation or flipping lossless (no image degradation), though metadata may be removed.

    Command Syntax:

    • Unix-like systems: jpegtran [switches] [inputfile] > outputfile.
    • Non-Unix systems: jpegtran [switches] inputfile outputfile.

    Lossless Transformations:

    • -flip horizontal: Mirror image horizontally.
    • -flip vertical: Mirror image vertically.
    • -rotate 90, -rotate 180, -rotate 270: Rotate the image.
    • -transpose: Transpose across UL-to-LR axis.
    • -transverse: Transverse transpose across UR-to-LL axis.
    • -crop WxH+X+Y: Losslessly crop to a rectangular subarea.
    • -trim: Drops non-transformable edge blocks (makes the transform non-lossless but avoids strange edge artifacts).

    Metadata Control:

    • -copy none: Discards all extra markers (comments, etc.).
    • -copy comments: Copies only comment markers.
    • -copy all: Preserves all extra markers (Exif, Photoshop settings, etc.).
    # Example: Rotate an image 90 degrees clockwise losslessly
    jpegtran -rotate 90 input.jpg -outfile rotated.jpg