{
  "name": "ImageDDS",
  "main": {
    "name": "ImageDDS",
    "namespace": "sofa::helper::io",
    "module": "Sofa.framework.Helper",
    "include": "sofa/helper/io/ImageDDS.h",
    "doc": "",
    "inherits": [
      "Image"
    ],
    "templates": [],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "load",
        "return_type": "bool",
        "params": [
          {
            "name": "filename",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "save",
        "return_type": "bool",
        "params": [
          {
            "name": "filename",
            "type": "int"
          },
          {
            "name": "compression_level",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "component": {
      "name": "sofa::helper::io::ImageDDS",
      "description": "The `sofa::helper::io::ImageDDS` class in the SOFA (Simulation Open-Framework Architecture) library provides functionality to read and write images in the DirectDraw Surface (DDS) format. DDS is a file format originally developed by Microsoft for storing textures and other graphics data in applications that use DirectX, but it has been adopted widely due to its support for various compression schemes and multi-resolution mipmaps.",
      "methods": [
        {
          "name": "load",
          "description": "Loads an image from a specified filename into the ImageDDS object. It parses the DDS header information to determine details such as the width, height, pixel format, pitch (the length of each row in memory), depth for 3D textures, number of mipmaps, and texture type (e.g., 2D, cube map). The method handles various pixel formats including uncompressed and compressed types. If an error occurs during loading or if the file is not recognized as a DDS file, it returns false."
        },
        {
          "name": "save",
          "description": "Saves the current image data to a specified filename in the DDS format. It constructs a header based on the properties of the ImageDDS object such as width, height, pixel format (based on SOFA's internal representation), number of mipmaps, and texture type. The method then writes this header followed by the image data to the file. If an error occurs during writing or if the specified image format is unsupported for saving in DDS, it returns false."
        }
      ],
      "attributes": [
        {
          "name": "m_format",
          "description": "Stores information about the pixel format used in the loaded image, including bits per channel and number of channels."
        },
        {
          "name": "m_data",
          "description": "Holds the raw image data as a vector of unsigned bytes (std::vector<unsigned char>). This contains the actual pixels that make up the image or texture."
        }
      ],
      "notes": "The DDS format supports multiple pixel formats including compressed types like DXT1 and DXT5, which can reduce file size at the cost of image quality. It also supports mipmaps for efficient rendering of distant textures and cube maps for representing environments in 3D applications.",
      "exampleUsage": {
        "loadExample": "sofa::helper::io::ImageDDS img; if (img.load(\"my_texture.dds\")) { // Image loaded successfully, use `img` to access the image data } else { // Failed to load image }",
        "saveExample": "sofa::helper::io::ImageDDS img; // Fill in `img` with appropriate data if (img.save(\"output_texture.dds\", 0)) { // Image saved successfully } else { // Failed to save image }"
      },
      "dependencies": [
        {
          "name": "SOFA library",
          "description": "This class is part of the SOFA simulation framework and depends on various components within that library, including utility functions for handling images."
        }
      ]
    }
  },
  "maths": {
    "maths": "The `ImageDDS` component in the SOFA framework is primarily involved in loading and saving DDS (DirectDraw Surface) images. It does not contribute to governing equations or operators typically found in FEM simulations, such as mass matrix M, stiffness matrix K, internal force f_int, residual R, etc., nor does it involve constitutive laws or kinematic models directly related to deformable bodies or continuum mechanics.\n\n### Role in the Global FEM Pipeline:\n- **ImageDDS** does not fit into the global FEM pipeline as it is primarily an input/output (I/O) component. Its main functions are `load` and `save`, which read and write DDS image files, respectively. These operations do not directly involve any of the steps in the computational mechanics simulation workflow such as spatial discretization, time integration, nonlinear solve, or linear solve.\n\n### Numerical Methods and Discretizations:\n- **Numerical methods**: The component uses standard file I/O functions (`fopen`, `fclose`, `fread`, `fwrite`) to handle DDS files. It parses the DDS header and pixel data according to predefined formats and bitmasks for various pixel formats (e.g., UNORM8, UNORM16, HALF, FLOAT).\n- **Discretization choices**: The component supports a variety of pixel formats and compression schemes, including DXT1, DXT5, ATI1N, ATI2N, RG16, RGBA16, R16F, RG16F, RGBA16F, R32F, RG32F, RGBA32F. It also supports mipmaps and different texture types (e.g., 2D textures, 3D volumes, cubemaps).\n\n### Fitting into the Broader Variational / Lagrangian Mechanics Framework:\n- **Variational mechanics**: The `ImageDDS` component is not directly related to variational mechanics or Lagrangian formulations of continuum mechanics. It serves a supporting role in loading and saving image data that could be used as texture maps for visualization purposes, but it does not contribute to the physical simulation itself.\n\n### Summary:\n- **Mathematical Content**: The component has minimal mathematical content, primarily dealing with bitwise operations and file I/O for handling DDS images. It is not involved in any of the core numerical or variational aspects typical of a FEM framework.\n- **Physical Description**: `ImageDDS` does not participate in physical modeling or simulations but can be used as part of the broader simulation pipeline to load textures that might be necessary for rendering purposes, e.g., visualizing simulated deformations on textured surfaces."
  },
  "summary": {
    "abstract": "`ImageDDS` loads and saves DDS (DirectDraw Surface) image files, serving as an input/output utility in the SOFA framework.",
    "sheet": "# ImageDDS\n\n**Overview**\n\nThe `ImageDDS` component is part of the `sofa::helper::io` namespace within the `Sofa.framework.Helper` module. It inherits from the `Image` class and provides functionality for loading and saving DDS image files, which can be used as texture maps in visualizations.\n\n**Parameters and Data**\n\nThe component does not expose any significant data fields or parameters beyond its inherited attributes from the parent `Image` class."
  }
}