wowlib::formats::blp::BLP Struct Reference

#include <wowlib/formats/blp/blp.hpp>

Inheritance diagram for wowlib::formats::blp::BLP:

Public Member Functions
Result< void >	read (std::span< const std::byte > data)
	Parse a BLP2 file from memory, replacing this entity's contents.
Result< FileBuffer >	write () const
	Serialize this entity.
Result< void >	read (fs::FileSystem &fs, const FileKey &key)
	Load the BLP from a client filesystem, replacing this entity's contents.
Result< void >	write (fs::FileSystem &fs, const FileKey &key) const
	Serialize and store the BLP through the filesystem's project overlay.
Result< Image >	decode () const
	Decode mip level 0 to an RGBA8 Image.
Result< Image >	decode (std::uint32_t level) const
	Decode one stored mip level to an RGBA8 Image.
Result< void >	encode (const Image &image)
	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, const EncodeSettings &settings)
	Rebuild the whole texture from an RGBA8 image: sets the header fields, quantizes/compresses every level and generates the mip chain per the settings.
std::size_t	mipCount () const
	The number of stored mip levels (level indices 0 .
Result< FileBuffer >	mip (std::uint32_t level) const
	One level's raw payload bytes (palette indices + alpha plane, DXT blocks, or BGRA pixels, per colorEncoding).
Result< void >	setMip (std::uint32_t level, std::span< const std::byte > data)
	Replace one level's raw payload bytes verbatim.
std::uint32_t	mipWidth (std::uint32_t level) const
	The pixel width of a mip level (level 0 halves per step, floored at 1).
std::uint32_t	mipHeight (std::uint32_t level) const
	The pixel height of a mip level (level 0 halves per step, floored at 1).
ValidationReport	validate () const
Result< void >	ensureValid () const
	Validate and raise on the first error instead of returning a report — the assert-style face of validate().
bool	operator== (const BLP &) const =default

Public Attributes
std::uint32_t	version = BlpVersion1
	The header version field; 1 in every shipped file.
ColorEncoding	colorEncoding = ColorEncoding::Dxt
	How the pixel payload is encoded.
std::uint8_t	alphaDepth = 8
	Alpha bits per pixel (0, 1, 4 or 8): the alpha plane depth for Palettized files, and a selection hint for DXT.
PixelFormat	preferredFormat = PixelFormat::Dxt5
	The client-side pixel format hint; selects the DXT block format for Dxt-encoded files.
std::uint8_t	mipFlags = 1
	The header's mip byte: 0 = level 0 only, 1 = generated mips, 2 = handmade mips (plus rare high flag bits, preserved verbatim).
std::uint32_t	width = 0
	The level-0 width in pixels.
std::uint32_t	height = 0
	The level-0 height in pixels.
std::array< CImVector, BlpPaletteSize >	palette {}
	The 256-entry color table of Palettized files (b, g, r + a padding byte, preserved verbatim).
std::vector< FileBuffer >	mips
	The raw mip payloads, indexed by level (empty vector = level absent).
detail::StoredLayout	storedLayout
	The read-recorded on-disk placement (see detail::StoredLayout).

Detailed Description

Definition at line 158 of file blp.hpp.

Member Function Documentation

decode() [1/2]

Result< Image > wowlib::formats::blp::BLP::decode ( ) const

nodiscard

Decode mip level 0 to an RGBA8 Image.

Returns

the decoded image

Definition at line 744 of file blp.cpp.

References decode().

Referenced by decode().

decode() [2/2]

Result< Image > wowlib::formats::blp::BLP::decode ( std::uint32_t level ) const

nodiscard

Decode one stored mip level to an RGBA8 Image.

Returns

the decoded image

Parameters

level

the mip level to decode

Definition at line 746 of file blp.cpp.

References alphaDepth, wowlib::formats::blp::Bgra, wowlib::formats::blp::BgraAlt, colorEncoding, wowlib::formats::blp::detail::DxtCodec::decode(), wowlib::formats::blp::detail::PaletteCodec::decode(), wowlib::formats::blp::detail::RawCodec::decode(), wowlib::formats::blp::Dxt, height, wowlib::InvalidEntityState, wowlib::formats::blp::Jpeg, wowlib::makeError(), mipHeight(), mips, mipWidth(), wowlib::NotSupported, palette, wowlib::formats::blp::Palettized, preferredFormat, and width.

encode() [1/2]

Result< void > wowlib::formats::blp::BLP::encode

(

const Image &

image

)

Rebuild the whole texture from an RGBA8 image with the default settings (DXT, alpha depth 8 -> BC3, full mip chain).

Parameters

image

the level-0 image; width * height * 4 pixel bytes

Definition at line 777 of file blp.cpp.

References encode().

Referenced by encode().

encode() [2/2]

Result< void > wowlib::formats::blp::BLP::encode	(	const Image &	image,
		const EncodeSettings &	settings )

Rebuild the whole texture from an RGBA8 image: sets the header fields, quantizes/compresses every level and generates the mip chain per the settings.

Parameters

image	the level-0 image; width * height * 4 pixel bytes
settings	encoding, block format, alpha depth and mip generation choices

Definition at line 781 of file blp.cpp.

References alphaDepth, wowlib::formats::blp::EncodeSettings::alphaDepth, wowlib::formats::blp::Argb8888, wowlib::formats::blp::Bgra, wowlib::formats::blp::BgraAlt, wowlib::formats::blp::BlpMaxMips, wowlib::formats::blp::BlpVersion1, wowlib::formats::blp::detail::PaletteCodec::buildPalette(), colorEncoding, wowlib::formats::blp::detail::MipmapScaler::downscale(), wowlib::formats::blp::Dxt, wowlib::formats::blp::Dxt1, wowlib::formats::blp::detail::DxtCodec::encode(), wowlib::formats::blp::detail::PaletteCodec::encode(), wowlib::formats::blp::detail::RawCodec::encode(), wowlib::formats::blp::EncodeSettings::encoding, wowlib::formats::blp::EncodeSettings::format, height, wowlib::formats::blp::Image::height, wowlib::InvalidEntityState, wowlib::formats::blp::Jpeg, wowlib::makeError(), mipFlags, wowlib::formats::blp::EncodeSettings::mipmaps, mips, wowlib::NotSupported, palette, wowlib::formats::blp::Palettized, wowlib::formats::blp::Image::pixels, preferredFormat, wowlib::formats::blp::Unspecified, version, width, and wowlib::formats::blp::Image::width.

ensureValid()

Result< void > wowlib::formats::blp::BLP::ensureValid ( ) const

inlinenodiscard

Validate and raise on the first error instead of returning a report — the assert-style face of validate().

Returns

nothing; raises when validate() finds any error

Definition at line 274 of file blp.hpp.

References validate().

mip()

Result< FileBuffer > wowlib::formats::blp::BLP::mip ( std::uint32_t level ) const

nodiscard

One level's raw payload bytes (palette indices + alpha plane, DXT blocks, or BGRA pixels, per colorEncoding).

Returns

a copy of the payload bytes

Parameters

level

the mip level

Definition at line 849 of file blp.cpp.

References wowlib::InvalidEntityState, wowlib::makeError(), and mips.

mipCount()

std::size_t wowlib::formats::blp::BLP::mipCount ( ) const

inline

The number of stored mip levels (level indices 0 .

. count - 1).

Definition at line 240 of file blp.hpp.

References mips.

mipHeight()

std::uint32_t wowlib::formats::blp::BLP::mipHeight ( std::uint32_t level ) const

inlinenodiscard

The pixel height of a mip level (level 0 halves per step, floored at 1).

Parameters

level

the mip level

Definition at line 261 of file blp.hpp.

References height.

Referenced by decode(), and validate().

mipWidth()

std::uint32_t wowlib::formats::blp::BLP::mipWidth ( std::uint32_t level ) const

inlinenodiscard

The pixel width of a mip level (level 0 halves per step, floored at 1).

Parameters

level

the mip level

Definition at line 255 of file blp.hpp.

References width.

Referenced by decode(), and validate().

operator==()

bool wowlib::formats::blp::BLP::operator== ( const BLP & ) const

default

read() [1/2]

Result< void > wowlib::formats::blp::BLP::read	(	fs::FileSystem &	fs,
		const FileKey &	key )

Load the BLP from a client filesystem, replacing this entity's contents.

Parameters

fs	the filesystem gateway
key	the file identity (path and/or FileDataID)

Definition at line 729 of file blp.cpp.

References read().

read() [2/2]

Result< void > wowlib::formats::blp::BLP::read

(

std::span< const std::byte >

data

)

Parse a BLP2 file from memory, replacing this entity's contents.

Parameters

data	the complete file bytes

Definition at line 596 of file blp.cpp.

References alphaDepth, wowlib::formats::blp::detail::BLPHeader::alphaDepth, wowlib::formats::blp::Bc5, wowlib::formats::blp::BgraAlt, wowlib::formats::blp::BlpHeaderBytes, wowlib::formats::blp::BlpMagic, wowlib::formats::blp::BlpMaxMips, wowlib::ChunkTruncated, colorEncoding, wowlib::formats::blp::detail::BLPHeader::colorEncoding, wowlib::FormatVersionMismatch, height, wowlib::formats::blp::detail::BLPHeader::height, wowlib::formats::blp::detail::BLPHeader::magic, wowlib::makeError(), mipFlags, wowlib::formats::blp::detail::BLPHeader::mipFlags, wowlib::formats::blp::detail::BLPHeader::mipOffsets, mips, wowlib::formats::blp::detail::BLPHeader::mipSizes, wowlib::NotSupported, wowlib::OffsetOutOfBounds, palette, preferredFormat, wowlib::formats::blp::detail::BLPHeader::preferredFormat, storedLayout, version, wowlib::formats::blp::detail::BLPHeader::version, width, and wowlib::formats::blp::detail::BLPHeader::width.

Referenced by read().

setMip()

Result< void > wowlib::formats::blp::BLP::setMip	(	std::uint32_t	level,
		std::span< const std::byte >	data )

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.

Parameters

level	the mip level
data	the payload bytes

Definition at line 856 of file blp.cpp.

References wowlib::formats::blp::BlpMaxMips, wowlib::InvalidEntityState, wowlib::makeError(), and mips.

validate()

ValidationReport wowlib::formats::blp::BLP::validate ( ) const

nodiscard

Returns

every violated contract, in level order

Definition at line 868 of file blp.cpp.

References wowlib::formats::ValidationReport::addError(), wowlib::formats::ValidationReport::addWarning(), alphaDepth, wowlib::formats::blp::Bgra, wowlib::formats::blp::BgraAlt, wowlib::formats::blp::BlpMaxMips, colorEncoding, wowlib::formats::blp::Dxt, wowlib::formats::blp::detail::DxtCodec::encodedSize(), wowlib::formats::ValidationReport::full(), height, wowlib::formats::blp::Jpeg, mipHeight(), mips, mipWidth(), wowlib::formats::blp::Palettized, preferredFormat, and width.

Referenced by ensureValid().

write() [1/2]

Result< FileBuffer > wowlib::formats::blp::BLP::write ( ) const

nodiscard

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.

Returns

the file bytes

Definition at line 668 of file blp.cpp.

References alphaDepth, wowlib::formats::blp::detail::BLPHeader::alphaDepth, wowlib::formats::blp::BlpHeaderBytes, wowlib::formats::blp::BlpMagic, wowlib::formats::blp::BlpMaxMips, wowlib::formats::blp::detail::StoredLayout::Run::bytes, colorEncoding, wowlib::formats::blp::detail::BLPHeader::colorEncoding, height, wowlib::formats::blp::detail::BLPHeader::height, wowlib::InvalidEntityState, wowlib::formats::blp::detail::BLPHeader::magic, wowlib::makeError(), mipFlags, wowlib::formats::blp::detail::BLPHeader::mipFlags, wowlib::formats::blp::detail::BLPHeader::mipOffsets, mips, wowlib::formats::blp::detail::BLPHeader::mipSizes, wowlib::formats::blp::detail::StoredLayout::Run::offset, palette, preferredFormat, wowlib::formats::blp::detail::BLPHeader::preferredFormat, storedLayout, version, wowlib::formats::blp::detail::BLPHeader::version, width, and wowlib::formats::blp::detail::BLPHeader::width.

Referenced by write().

write() [2/2]

Result< void > wowlib::formats::blp::BLP::write	(	fs::FileSystem &	fs,
		const FileKey &	key ) const

Serialize and store the BLP through the filesystem's project overlay.

Parameters

fs	the filesystem gateway
key	the file identity; must resolve to a path

Definition at line 735 of file blp.cpp.

References wowlib::makeError(), wowlib::FileKey::path, wowlib::PathNotResolvable, and write().

Member Data Documentation

alphaDepth

std::uint8_t wowlib::formats::blp::BLP::alphaDepth = 8

Alpha bits per pixel (0, 1, 4 or 8): the alpha plane depth for Palettized files, and a selection hint for DXT.

Definition at line 166 of file blp.hpp.

Referenced by decode(), encode(), read(), validate(), and write().

colorEncoding

ColorEncoding wowlib::formats::blp::BLP::colorEncoding = ColorEncoding::Dxt

How the pixel payload is encoded.

Definition at line 163 of file blp.hpp.

Referenced by decode(), encode(), read(), validate(), and write().

height

std::uint32_t wowlib::formats::blp::BLP::height = 0

The level-0 height in pixels.

Definition at line 178 of file blp.hpp.

Referenced by decode(), encode(), mipHeight(), read(), validate(), and write().

mipFlags

std::uint8_t wowlib::formats::blp::BLP::mipFlags = 1

The header's mip byte: 0 = level 0 only, 1 = generated mips, 2 = handmade mips (plus rare high flag bits, preserved verbatim).

Definition at line 172 of file blp.hpp.

Referenced by encode(), read(), and write().

mips

std::vector<FileBuffer> wowlib::formats::blp::BLP::mips

The raw mip payloads, indexed by level (empty vector = level absent).

Exposed to the bindings through mip()/setMip(); kept verbatim for the byte-perfect round-trip.

Definition at line 186 of file blp.hpp.

Referenced by decode(), encode(), mip(), mipCount(), read(), setMip(), validate(), and write().

palette

std::array<CImVector, BlpPaletteSize> wowlib::formats::blp::BLP::palette {}

The 256-entry color table of Palettized files (b, g, r + a padding byte, preserved verbatim).

Present but unused for Dxt/Bgra files.

Definition at line 181 of file blp.hpp.

Referenced by decode(), encode(), read(), and write().

preferredFormat

PixelFormat wowlib::formats::blp::BLP::preferredFormat = PixelFormat::Dxt5

The client-side pixel format hint; selects the DXT block format for Dxt-encoded files.

Definition at line 169 of file blp.hpp.

Referenced by decode(), encode(), read(), validate(), and write().

storedLayout

detail::StoredLayout wowlib::formats::blp::BLP::storedLayout

The read-recorded on-disk placement (see detail::StoredLayout).

Definition at line 189 of file blp.hpp.

Referenced by read(), and write().

version

std::uint32_t wowlib::formats::blp::BLP::version = BlpVersion1

The header version field; 1 in every shipped file.

Definition at line 160 of file blp.hpp.

Referenced by encode(), read(), and write().

width

std::uint32_t wowlib::formats::blp::BLP::width = 0

The level-0 width in pixels.

Definition at line 175 of file blp.hpp.

Referenced by decode(), encode(), mipWidth(), read(), validate(), and write().

---

The documentation for this struct was generated from the following files:

• src/wowlib/formats/blp/blp.hpp
• src/wowlib/formats/blp/blp.cpp