blp.hpp

Go to the documentation of this file.

#pragma once

 
#include <algorithm>
#include <array>
#include <cstddef>
#include <cstdint>
#include <span>
#include <type_traits>
#include <vector>
 
#include <welder/vocabulary.hpp>
 
#include <wowlib/core/buffer.hpp>
#include <wowlib/core/error.hpp>
#include <wowlib/core/file_key.hpp>
#include <wowlib/formats/common/fourcc.hpp>
#include <wowlib/formats/common/types.hpp>
#include <wowlib/formats/common/validation.hpp>
#include <wowlib/fs/filesystem.hpp>
#include <wowlib/formats/common/file_entity.hpp>
 
namespace wowlib::formats::blp {
  inline constexpr std::uint32_t BlpMagic = fourcc("BLP2", FourCCEndian::Forward);
  inline constexpr std::uint32_t BlpVersion1 = 1;
  inline constexpr std::size_t BlpMaxMips = 16;
  inline constexpr std::size_t BlpPaletteSize = 256;
  inline constexpr std::size_t BlpHeaderBytes = 0x494;
 
  enum class [[
      =welder::weld,
      =welder::doc("How a BLP's pixel payload is encoded (the header's "
        "colorEncoding byte).")
    ]] ColorEncoding : std::uint8_t {
    Jpeg [[=welder::doc("JPEG-compressed content (Warcraft III heritage; never "
      "shipped in WoW clients — wowlib preserves but cannot "
      "decode it).")]] = 0,
    Palettized [[=welder::doc("256-color palette indices, one byte per pixel, "
      "followed by a separate alpha plane of "
      "alphaDepth bits per pixel.")]] = 1,
    Dxt [[=welder::doc("DXT/S3TC block compression; the variant (BC1/BC2/BC3/"
      "BC5) follows from preferred_format and "
      "alphaDepth.")]] = 2,
    Bgra [[=welder::doc("Raw 32-bit BGRA pixels (Cataclysm+; terrain cube "
      "maps).")]] = 3,
    BgraAlt [[=welder::doc("Raw 32-bit BGRA under a different client-side "
      "PIXEL_FORMAT; identical file content to "
      "Bgra.")]] = 4,
  };
 
  enum class [[
      =welder::weld,
      =welder::doc("The client-side pixel format hint (the header's "
        "preferredFormat byte). For DXT-encoded files it selects the "
        "block format: Dxt1 -> BC1, Dxt3 -> BC2, Dxt5 -> BC3, "
        "Bc5 -> BC5.")
    ]] PixelFormat : std::uint8_t {
    Dxt1 [[=welder::doc("BC1: 8-byte blocks, optional 1-bit punch-through "
      "alpha.")]] = 0,
    Dxt3 [[=welder::doc("BC2: 16-byte blocks, explicit 4-bit alpha.")]] = 1,
    Argb8888 [[=welder::doc("Raw 32-bit upload hint (used by Bgra-encoded "
      "files).")]] = 2,
    Argb1555 [[=welder::doc("16-bit 1555 upload hint; never a file "
      "content layout.")]] = 3,
    Argb4444 [[=welder::doc("16-bit 4444 upload hint; never a file "
      "content layout.")]] = 4,
    Rgb565 [[=welder::doc("16-bit 565 upload hint; never a file content "
      "layout.")]] = 5,
    A8 [[=welder::doc("Alpha-only upload hint; never a file content "
      "layout.")]] = 6,
    Dxt5 [[=welder::doc("BC3: 16-byte blocks, interpolated 8-bit alpha.")]] = 7,
    Unspecified [[=welder::doc("No preference recorded (typical for palettized "
      "files).")]] = 8,
    Argb2565 [[=welder::doc("Component-texture upload hint; never a file "
      "content layout.")]] = 9,
    Bc5 [[=welder::doc("BC5: two interpolated channels (normal maps, later "
      "clients).")]] = 11,
  };
 
  namespace detail {
        palette follows it). The entity decomposes these fields into welded
        members; this struct exists for layout-exact serialization. */
    struct BLPHeader {
      std::uint32_t magic = BlpMagic; 
      std::uint32_t version = BlpVersion1; 
      std::uint8_t colorEncoding = 2; 
      std::uint8_t alphaDepth = 0; 
      std::uint8_t preferredFormat = 0; 
      std::uint8_t mipFlags = 0; 
      std::uint32_t width = 0; 
      std::uint32_t height = 0; 
      std::array<std::uint32_t, BlpMaxMips> mipOffsets{};
      std::array<std::uint32_t, BlpMaxMips> mipSizes{};
    };
 
    static_assert(sizeof(BLPHeader) == 0x94);
    static_assert(std::is_trivially_copyable_v<BLPHeader>);


        bytes, non-contiguous or shared mip placement) still round-trip
        byte-perfectly. Disengaged (fresh entity, or payload sizes changed):
        write() lays the file out canonically — header, then the levels
        back-to-back in level order. */
    struct StoredLayout {
      struct Run {
        std::uint32_t offset = 0; 
        FileBuffer bytes; 
 
        bool operator==(const Run&) const = default;
      };
 
      std::array<std::uint32_t, BlpMaxMips> offsets{};
      std::array<std::uint32_t, BlpMaxMips> sizes{};
      std::uint32_t fileSize = 0; 
      std::vector<Run> gaps; 
      bool engaged = false; 
 
      bool operator==(const StoredLayout&) const = default;
    };
  }
 
  struct [[
      =welder::weld,
      =welder::doc(R"(
        A decoded texture surface: 8-bit RGBA pixels in row-major order, row 0
        at the top. pixels holds width * height * 4 bytes (r, g, b, a per
        pixel) and maps to NumPy zero-copy; reshape to (height, width, 4).)")
    ]] Image {
    [[=welder::doc("The width in pixels.")]]
    std::uint32_t width = 0;
 
    [[=welder::doc("The height in pixels.")]]
    std::uint32_t height = 0;
 
    [[=welder::mark::no_reassign,
      =welder::doc("The RGBA8 pixel bytes, width * height * 4, row-major from "
        "the top-left.")]]
    std::vector<std::uint8_t> pixels;
 
    bool operator==(const Image&) const = default;
  };
 
  struct [[
      =welder::weld,
      =welder::doc(R"(
        How encode() should build the file. The defaults produce what the
        client ships most: DXT compression with the block format chosen from
        the alpha depth (0 -> BC1, 1 -> BC1 punch-through, 4 -> BC2,
        8 -> BC3), with a full generated mip chain.)")
    ]] EncodeSettings {
    [[=welder::doc("The payload encoding to produce (Palettized, Dxt or "
      "Bgra; Jpeg is not supported).")]]
    ColorEncoding encoding = ColorEncoding::Dxt;
 
    [[=welder::doc("The DXT block format for Dxt encoding (Dxt1, Dxt3, Dxt5 "
      "or Bc5). Unspecified picks from alphaDepth: 0/1 -> Dxt1, "
      "4 -> Dxt3, 8 -> Dxt5. Ignored for Palettized/Bgra.")]]
    PixelFormat format = PixelFormat::Unspecified;
 
    [[=welder::doc("Alpha bits per pixel: 0, 1, 4 or 8. Selects the alpha "
      "plane depth for Palettized files and the block format for "
      "Dxt when format is Unspecified.")]]
    std::uint8_t alphaDepth = 8;
 
    [[=welder::doc("Whether to generate the full mip chain down to 1x1 "
      "(box-filtered). Off: the file holds only level 0.")]]
    bool mipmaps = true;
 
    bool operator==(const EncodeSettings&) const = default;
  };
 
  struct [[
      =welder::weld,
      // The dotnet style would coerce the all-caps identifier to Blp; the
      // format acronym is the name (round-1 API feedback). Python already
      // spells BLP, so the rename is cs-scoped.
      =welder::weld_as(wowlib::lang::Cs, "BLP"),
      =welder::doc(R"(
        A BLP2 texture file — every WoW client release reads the same layout,
        so the class carries no client-version axis. read()/write() move the
        file whole with a byte-perfect round-trip while the mip payloads are
        unmodified; decode(level) produces an RGBA8 Image from a stored level
        (palettized, DXT1/3/5, BC5 and raw BGRA all decode); encode(image,
        settings) rebuilds the palette/compression/mip chain from one. Raw
        payload access goes through mip()/set_mip(). See
        https://wowdev.wiki/BLP.)")
    ]] BLP : FileEntityBase {
    [[=welder::doc("The header version field; 1 in every shipped file.")]]
    std::uint32_t version = BlpVersion1;
 
    [[=welder::doc("How the pixel payload is encoded.")]]
    ColorEncoding colorEncoding = ColorEncoding::Dxt;
 
    [[=welder::doc("Alpha bits per pixel (0, 1, 4 or 8): the alpha plane "
      "depth for Palettized files, and a selection hint for "
      "DXT.")]]
    std::uint8_t alphaDepth = 8;
 
    [[=welder::doc("The client-side pixel format hint; selects the DXT block "
      "format for Dxt-encoded files.")]]
    PixelFormat preferredFormat = PixelFormat::Dxt5;
 
    [[=welder::doc("The header's mip byte: 0 = level 0 only, 1 = generated "
      "mips, 2 = handmade mips (plus rare high flag bits, "
      "preserved verbatim).")]]
    std::uint8_t mipFlags = 1;
 
    [[=welder::doc("The level-0 width in pixels.")]]
    std::uint32_t width = 0;
 
    [[=welder::doc("The level-0 height in pixels.")]]
    std::uint32_t height = 0;
 
    [[=welder::doc("The 256-entry color table of Palettized files (b, g, r + "
      "a padding byte, preserved verbatim). Present but unused "
      "for Dxt/Bgra files.")]]
    std::array<CImVector, BlpPaletteSize> palette{};

    [[=welder::mark::exclude]]
    std::vector<FileBuffer> mips;


    [[=welder::mark::exclude]]
    detail::StoredLayout storedLayout;
 
    // --- serialization --------------------------------------------------------
 
    [[=welder::doc("Parse a BLP2 file from memory, replacing this entity's "
      "contents.")]]
    Result<void> read(std::span<const std::byte> data [[=welder::doc("the complete file bytes")]]);
 
    [[nodiscard]]
    [[=welder::doc("Serialize this entity. While the mip payloads are "
        "unmodified the original file's exact layout is replayed, "
        "so an unmodified read rewrites byte-for-byte."),
      =welder::returns("the file bytes")]]
    Result<FileBuffer> write() const;
 
    [[=welder::doc("Load the BLP from a client filesystem, replacing this "
      "entity's contents.")]]
    Result<void> read(fs::FileSystem& fs [[=welder::doc("the filesystem gateway")]],
                      const FileKey& key [[=welder::doc("the file identity (path and/or FileDataID)")]]);
 
    [[=welder::doc("Serialize and store the BLP through the filesystem's "
      "project overlay.")]]
    Result<void> write(fs::FileSystem& fs [[=welder::doc("the filesystem gateway")]],
                       const FileKey& key [[=welder::doc("the file identity; must resolve to a path")]]) const;
 
    // --- the image surface ----------------------------------------------------
 
    [[nodiscard]]
    [[=welder::doc("Decode mip level 0 to an RGBA8 Image."),
      =welder::returns("the decoded image")]]
    Result<Image> decode() const;
 
    [[nodiscard]]
    [[=welder::doc("Decode one stored mip level to an RGBA8 Image."),
      =welder::returns("the decoded image")]]
    Result<Image> decode(std::uint32_t level [[=welder::doc("the mip level to decode")]]) const;
 
    [[=welder::doc("Rebuild the whole texture from an RGBA8 image with the "
      "default settings (DXT, alpha depth 8 -> BC3, full mip "
      "chain).")]]
    Result<void> encode(const Image& image
      [[=welder::doc("the level-0 image; width * height * 4 "
        "pixel bytes")]]);
 
    [[=welder::doc("Rebuild the whole texture from an RGBA8 image: sets the "
      "header fields, quantizes/compresses every level and "
      "generates the mip chain per the settings.")]]
    Result<void> encode(const Image& image
                        [[=welder::doc("the level-0 image; width * height * 4 "
                          "pixel bytes")]],
                        const EncodeSettings& settings
                        [[=welder::doc("encoding, block format, alpha depth "
                          "and mip generation choices")]]);
 
    // --- raw mip access -------------------------------------------------------
 
    [[=welder::getter,
      =welder::doc("The number of stored mip levels (level indices 0 .. "
        "count - 1).")]]
    std::size_t mipCount() const { return mips.size(); }
 
    [[nodiscard]]
    [[=welder::doc("One level's raw payload bytes (palette indices + alpha "
        "plane, DXT blocks, or BGRA pixels, per colorEncoding)."),
      =welder::returns("a copy of the payload bytes")]]
    Result<FileBuffer> mip(std::uint32_t level [[=welder::doc("the mip level")]]) const;
 
    [[=welder::doc("Replace one level's raw payload bytes verbatim. The "
      "caller owns their consistency with the header fields; "
      "changing a payload's size switches write() to the "
      "canonical contiguous layout.")]]
    Result<void> setMip(std::uint32_t level [[=welder::doc("the mip level")]],
                         std::span<const std::byte> data [[=welder::doc("the payload bytes")]]);
 
    [[nodiscard]]
    [[=welder::doc("The pixel width of a mip level (level 0 halves per step, "
      "floored at 1).")]]
    std::uint32_t mipWidth(std::uint32_t level [[=welder::doc("the mip level")]]) const {
      return std::max<std::uint32_t>(1, width >> level);
    }
 
    [[nodiscard]]
    [[=welder::doc("The pixel height of a mip level (level 0 halves per step, "
      "floored at 1).")]]
    std::uint32_t mipHeight(std::uint32_t level [[=welder::doc("the mip level")]]) const {
      return std::max<std::uint32_t>(1, height >> level);
    }
 
    [[nodiscard]]
    [[=welder::doc(R"(
        Check the logical integrity contracts this texture must satisfy for the
        client to decode it — the base level's presence, the dimensions, and
        every stored level covering the pixels its size implies. write() never
        runs this; call it before writing when you want to know the result will
        load.)"),
      =welder::returns("every violated contract, in level order")]]
    ValidationReport validate() const;
 
    [[nodiscard]]
    [[=welder::doc("Validate and raise on the first error instead of returning "
        "a report — the assert-style face of validate()."),
      =welder::returns("nothing; raises when validate() finds any error")]]
    Result<void> ensureValid() const { return validate().toResult(); }
 
    bool operator==(const BLP&) const = default;
  };
}