Texture IO and Encoding

Texture I/O and Encoding (texio)

Relevant source files

The following files were used as context for generating this wiki page:

• clarity/texio.py

Purpose and Scope

The clarity/texio.py module manages texture input/output operations, acting as the bridge between vanilla game .tex binary assets and the upscaled pipeline's internal RGBA representation clarity/texio.py:1-8. It provides dual encoding pathways—leveraging hardware-accelerated GPU execution via texconv.exe or falling back to a pure Python/NumPy encoder (bc7enc) when external binaries are unavailable clarity/texio.py:1-8.

This page serves as a parent overview. For low-level algorithmic details, see child pages:

• Format Policy, Mip Chains and Tiers
• texconv Integration and Batching

graph TD
    subgraph "Natural Language Space: Texture Pipeline"
        VanillaTex["Vanilla .tex File"] --> Read["Read and Decode"]
        Read --> Upscale["Neural Upscaling Engine"]
        Upscale --> EncodeChoice["Dual Encode Path Selection"]
    end

    subgraph "Code Entity Space: clarity/texio.py"
        Read --> ReadFunc["texio.read()"]
        EncodeChoice --> UseTexconv["texio.use_texconv()"]
        UseTexconv -->|True| TexconvPath["texio._texconv()"]
        UseTexconv -->|False| NumpyPath["bc7enc Pure-Python Encoder"]
        TexconvPath --> DDSWrap["texio._dds_rgba()"]
        DDSWrap --> TexconvExe["texconv.exe (DirectXTex)"]
    end

    style VanillaTex fill:#fff,stroke:#333,stroke-width:2px
    style ReadFunc fill:#fff,stroke:#333,stroke-width:2px
    style UseTexconv fill:#fff,stroke:#333,stroke-width:2px
    style TexconvPath fill:#fff,stroke:#333,stroke-width:2px
    style NumpyPath fill:#fff,stroke:#333,stroke-width:2px
    style DDSWrap fill:#fff,stroke:#333,stroke-width:2px
    style TexconvExe fill:#fff,stroke:#333,stroke-width:2px

Loading

Figure 1: Texture I/O architectural flow mapping high-level concepts to functions in clarity/texio.py.

Sources: clarity/texio.py:1-135

---

6.1 Format Policy, Mip Chains and Tiers

Texture serialization policies govern how textures are output, which compression formats are applied (such as BC7, BC3, BC1, or BGRA8), and how mipmap chains are generated. The module calculates full mipmap levels based on texture dimensions using full_mips(w, h) [clarity/texio.py:106-107] and wraps uncompressed RGBA payloads into DDS containers via _dds_rgba [clarity/texio.py:114-135] to feed external encoders.

For detailed documentation on output format policies (out_format), box filtering for float chains, tier-based encoding configurations, and DDS wrapper mechanics, refer to the child page:

• Format Policy, Mip Chains and Tiers

Sources: clarity/texio.py:38-48, clarity/texio.py:106-150

---

6.2 texconv Integration and Batching

Performance heavily relies on external DirectXTex tooling. The texio module probes for available binaries through use_texconv() and probe_texconv() [clarity/texio.py:42-47, 62-92], detects debug versus release builds via is_debug_build() [clarity/texio.py:50-60], and manages batch execution pools with robust process-group isolation (CREATE_NEW_PROCESS_GROUP) to prevent premature termination on user interruption [clarity/texio.py:176-187].

For detailed documentation on scratch directory usage, batching routines (_texconv_many), failure retry logic, and benchmarking scripts, refer to the child page:

• texconv Integration and Batching

Sources: clarity/texio.py:42-92, clarity/texio.py:176-194