whiteoutlib 0.1.2

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

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

#pragma once

/**
 * @file parser.h
 * @brief WEM file parser
 *
 * This file provides the Parser class for reading and parsing WEM model files.
 * The parser handles the chunk-based WEM binary format.
 *
 * @example Basic parsing
 * @code
 * wem::Parser parser;
 * auto model = parser.parse("model.wem");
 *
 * if (model && parser.hasIssues()) {
 *     for (const auto& issue : parser.getIssues()) {
 *         std::cout << "Warning: " << issue << std::endl;
 *     }
 * }
 * @endcode
 */

#include <memory>
#include <string>
#include <vector>

#include "../../compatibility.h"
#include "structures.h"

namespace whiteout {
namespace models {
namespace wem {

// ============================================================================
// WEM Parser
// ============================================================================

/**
 * @brief Parser for WEM model files
 *
 * The Parser reads binary WEM files and converts them into the Model structure.
 * It supports strict and lenient parsing modes.
 *
 * Uses the PImpl (Pointer to Implementation) idiom to hide implementation details.
 */
class Parser {
public:
    /// @brief Construct a new Parser.
    Parser();

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

    /**
     * @brief Parse a WEM file from disk
     * @param filePath Path to the WEM file
     * @return Parsed model, or nullopt on failure in lenient mode
     * @throws std::runtime_error If file cannot be opened or parsing fails in strict mode
     */
    std::optional<Model> parse(const std::string& filePath);

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

    /**
     * @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 wem
} // namespace models
} // namespace whiteout