whiteoutlib 0.1.1

Read and write Blizzard game assets: models (MDX, M2, M3), textures (BLP, DDS, PNG, ...) and archives (CASC, MPQ).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

// SPDX-License-Identifier: BSD-3-Clause
// Copyright (c) 2026 Fernando Sahmkow

/// @file srgb_linearize.cpp
/// @brief Implementation of sRGB linearization utility.

#include "srgb_linearize.h"

#include <algorithm>
#include <array>
#include <cmath>

namespace whiteout::textures {

namespace {

// IEC 61966-2-1 sRGB transfer function constants.
constexpr f32 kSrgbLinearCutoff = 0.04045f;
constexpr f32 kSrgbCurveOffset = 0.055f;
constexpr f32 kSrgbCurveScale = 1.0f + kSrgbCurveOffset;
constexpr f32 kSrgbLinearSlope = 12.92f;
constexpr f32 kSrgbGamma = 2.4f;
constexpr f32 kSrgbInverseGamma = 1.0f / kSrgbGamma;
constexpr f32 kSrgbInverseCutoff = kSrgbLinearCutoff / kSrgbLinearSlope;

constexpr u32 kLutEntries = 256;
constexpr f32 kU8Max = 255.0f;
constexpr f32 kRoundingBias = 0.5f;

const std::array<u8, kLutEntries>& srgbToLinearLUT() {
    static const auto lut = [] {
        std::array<u8, kLutEntries> t{};
        for (u32 i = 0; i < kLutEntries; ++i) {
            const f32 s = static_cast<f32>(i) / kU8Max;
            const f32 l = (s <= kSrgbLinearCutoff)
                              ? (s / kSrgbLinearSlope)
                              : std::pow((s + kSrgbCurveOffset) / kSrgbCurveScale, kSrgbGamma);
            t[i] = static_cast<u8>(std::clamp(l * kU8Max + kRoundingBias, 0.0f, kU8Max));
        }
        return t;
    }();
    return lut;
}

const std::array<u8, kLutEntries>& linearToSrgbLUT() {
    static const auto lut = [] {
        std::array<u8, kLutEntries> t{};
        for (u32 i = 0; i < kLutEntries; ++i) {
            const f32 l = static_cast<f32>(i) / kU8Max;
            const f32 s =
                (l <= kSrgbInverseCutoff)
                    ? (l * kSrgbLinearSlope)
                    : (kSrgbCurveScale * std::pow(l, kSrgbInverseGamma) - kSrgbCurveOffset);
            t[i] = static_cast<u8>(std::clamp(s * kU8Max + kRoundingBias, 0.0f, kU8Max));
        }
        return t;
    }();
    return lut;
}

} // anonymous namespace

Texture linearizeSrgbCopy(const Texture& texture) {
    if (!texture.isSrgb())
        return Texture{texture}; // plain copy

    // Decompress BCn → RGBA8 if necessary.
    Texture work = (blockEdge(texture.format()) > 1) ? texture.copyAsFormat(PixelFormat::RGBA8)
                                                     : Texture{texture};

    const auto& lut = srgbToLinearLUT();
    const u32 channels = bytesPerBlock(work.format()); // bytes-per-pixel for uncompressed
    // Only convert colour channels (first 3); leave alpha untouched.
    const u32 colorCh = std::min(channels, 3u);

    u8* ptr = work.dataPtr();
    const u64 total = work.dataSize();

    for (u64 i = 0; i < total; i += channels) {
        for (u32 c = 0; c < colorCh; ++c)
            ptr[i + c] = lut[ptr[i + c]];
    }

    work.setSrgb(false);
    return work;
}

void ensureColorSpace(Texture& tex, bool srgb) {
    if (tex.isSrgb() == srgb)
        return;

    // Decompress BCn → RGBA8 if necessary.
    if (blockEdge(tex.format()) > 1)
        tex.format(PixelFormat::RGBA8);

    const u32 channels = bytesPerBlock(tex.format());
    const u32 colorCh = std::min(channels, 3u);

    // Pick the appropriate u8 LUT for the conversion direction.
    const auto& lut = srgb ? linearToSrgbLUT() : srgbToLinearLUT();

    u8* ptr = tex.dataPtr();
    const u64 total = tex.dataSize();

    for (u64 i = 0; i < total; i += channels) {
        for (u32 c = 0; c < colorCh; ++c)
            ptr[i + c] = lut[ptr[i + c]];
    }

    tex.setSrgb(srgb);
}

} // namespace whiteout::textures