whiteoutlib 0.1.6

Read and write Blizzard game assets from Rust: models (MDX, M2, M3), textures (BLP, DDS, PNG, JPEG, BMP, TGA, TIFF, GIF) 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

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

#pragma once

/**
 * @file parser.h
 * @brief BLP file parser
 *
 * This file provides the Parser class for reading and decoding BLP texture files.
 * The parser can handle both BLP1 (Warcraft III) and BLP2 (WoW) formats with
 * JPEG, palettized, DXT, and BGRA encodings.
 *
 * @example Basic parsing
 * @code
 * blp::Parser parser;
 * auto texture = parser.parse("texture.blp");
 *
 * if (parser.hasIssues()) {
 *     for (const auto& issue : parser.getIssues()) {
 *         std::cout << "Warning: " << issue << std::endl;
 *     }
 * }
 * @endcode
 */

#include <memory>
#include <optional>
#include <span>
#include <string>
#include <vector>

#include <whiteout/common_types.h>
#include <whiteout/textures/parser.h>
#include <whiteout/textures/texture.h>

namespace whiteout::textures::blp {

// ============================================================================
// BLP Parser
// ============================================================================

/**
 * @brief Parser for BLP texture files
 *
 * The Parser reads binary BLP files and converts them into the Texture
 * structure. It can handle both BLP1 (Warcraft III) and BLP2 (World of
 * Warcraft) variants. Parsing is non-throwing — issues are collected via
 * `hasIssues()` / `getIssues()` and `parse()` returns `std::nullopt` on
 * failure.
 *
 * Uses the PImpl (Pointer to Implementation) idiom to hide implementation details.
 */
/// @bind methods=buffer_only, js_name=BlpParser
class Parser : public textures::Parser {
public:
    /// @brief Construct a new Parser.
    Parser();

    /// @brief Destructor (defined in .cpp for incomplete type)
    ~Parser();

    /**
     * @brief Parse a BLP file from disk
     * @param filePath Path to the BLP file
     * @return Parsed texture data, or std::nullopt on failure
     */
    std::optional<Texture> parse(const std::string& filePath) override;

    /**
     * @brief Parse a BLP file from memory buffer
     * @param buffer Memory buffer containing BLP data
     * @return Parsed texture data, or std::nullopt on failure
     * @throws std::runtime_error If parsing fails in strict mode
     */
    std::optional<Texture> parse(std::span<const u8> buffer) override;

    /**
     * @brief Check if parsing encountered any issues
     * @return True if there were warnings or recoverable errors
     */
    bool hasIssues() const;

    /**
     * @brief Get list of issues encountered during parsing
     * @return Vector of issue description strings
     */
    const std::vector<std::string>& getIssues() const;

private:
    class Impl;
    std::unique_ptr<Impl> pImpl;
};

} // namespace whiteout::textures::blp