annotations.hpp File Reference

The chunk annotation vocabulary format entities declare their binary mapping with. More...

#include <meta>
#include <cstdint>
#include <string_view>
#include <wowlib/core/client_version.hpp>
#include <wowlib/formats/common/fourcc.hpp>

Include dependency graph for annotations.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	wowlib::formats::detail::ChunkSpec
	Stored form of a chunk annotation: the member's binary identity. More...
struct	wowlib::formats::detail::SinceSpec
	Stored form of since: member active for entity versions >= v. More...
struct	wowlib::formats::detail::UntilSpec
	Stored form of until: member active for entity versions < v. More...
struct	wowlib::formats::detail::OptionalSpec
	Stored form of optional: absence on read is not an error. More...
struct	wowlib::formats::detail::HeaderSpec
	Stored form of header: raw leading bytes of a container payload, memcpy'd before chunk scanning starts — not a chunk of its own. More...
struct	wowlib::formats::detail::ContainerSpec
	Stored form of container: the chunk payload is itself a chunk stream; the member is a nested chunked entity read recursively. More...
struct	wowlib::formats::detail::RepeatsSpec
	Stored form of repeats: the chunk may appear up to max times. More...
struct	wowlib::formats::detail::RepeatingSpec
	Stored form of repeating: the chunk appears once per element, any number of times (WDL MARE tiles, _mpv PVMI/PVPD/PVBD groups). More...
struct	wowlib::formats::detail::SequenceDataSpec
	Stored form of SequenceData (offset entities): the member's nested per-element data may live in an external buffer (M2 .anim files) — the engine resolves each outer element's base span/sink through the I/O context instead of assuming the entity's own buffer. More...
struct	wowlib::formats::detail::GatedBySpec
	Stored form of gatedBy (offset entities): the member occupies binary bytes only when the entity's globalFlags has any mask bit set. More...
struct	wowlib::formats::detail::OffsetAfterSpec
	Stored form of offsetAfter (offset entities): the trait-base member's positional layout position — right after the named own member of the entity. More...
struct	wowlib::formats::detail::CountMatchesSpec
	Stored form of countMatches: when the member is engaged, its element count times scale must equal the named sibling member's count. More...
struct	wowlib::formats::detail::CountMultipleOfSpec
	Stored form of countMultipleOf: the member's element count must be a multiple of divisor. More...
struct	wowlib::formats::detail::CountExactlySpec
	Stored form of countExactly: the member's element count is fixed by the format (an ADT map chunk's 145 height samples). More...
struct	wowlib::formats::detail::IndexesSpec
	Stored form of indexes: every element of the (integral) vector member must be a valid index into the named sibling member. More...
struct	wowlib::formats::detail::IndexesOptionalSpec
	Stored form of indexesOptional: like indexes, but the client's "no reference" sentinel (a negative value, or the all-ones value of an unsigned element) is a legal element. More...
struct	wowlib::formats::detail::IndexesInRootSpec
	Stored form of indexesInRoot: every element of the (integral) vector member must be a valid index into the named member of the ASSEMBLY's root entity. More...
struct	wowlib::formats::detail::ExpectedValueSpec
	Stored form of expectedValue: the (integral) data member must hold exactly this value (format-version fields). More...
struct	wowlib::formats::detail::NonemptySpec
	Stored form of nonempty: the member must hold data for the file to be meaningful to the client, even though read() tolerates its absence. More...

Namespaces
namespace	wowlib
namespace	wowlib::formats
namespace	wowlib::formats::detail

Functions
consteval detail::ChunkSpec	wowlib::formats::chunk (const char(&cc)[5], FourCCEndian endian=FourCCEndian::Reversed)
	Declare the chunk a member maps to.
consteval detail::SinceSpec	wowlib::formats::since (ClientVersion v)
	Restrict a member to entity versions >= v (inclusive).
consteval detail::UntilSpec	wowlib::formats::until (ClientVersion v)
	Restrict a member to entity versions < v (exclusive).
consteval detail::RepeatsSpec	wowlib::formats::repeats (std::uint32_t max)
	Allow a chunk to appear up to max times (e.g.
consteval detail::GatedBySpec	wowlib::formats::gatedBy (std::uint32_t mask)
	Make an offset-entity member's binary presence conditional on the entity's globalFlags: it occupies bytes only when globalFlags & mask is non-zero (M2's textureCombinerCombos behind global flag 0x8).
consteval detail::OffsetAfterSpec	wowlib::formats::offsetAfter (std::string_view name)
	Anchor a version-trait member at its positional layout position: the offset serializer walks the entity's OWN members in declaration order and splices each trait-base member right after the own member named here.
consteval detail::CountMatchesSpec	wowlib::formats::countMatches (std::string_view name, std::uint32_t scale=1)
	Declare a companion-count contract: when this member is engaged (non-empty), its element count times scale must equal the named sibling member's count.
consteval detail::CountMultipleOfSpec	wowlib::formats::countMultipleOf (std::uint32_t divisor)
	Declare a granularity contract: the member's element count must be a multiple of divisor (triangle index arrays: 3).
consteval detail::CountExactlySpec	wowlib::formats::countExactly (std::uint32_t count)
	Declare a fixed-size contract: when engaged, the member holds exactly count elements because the format fixes the grid (an ADT map chunk's 145 height samples, its 4096-byte shadow map).
consteval detail::IndexesSpec	wowlib::formats::indexes (std::string_view name)
	Declare a referential contract: every element of this (integral) vector member is an index into the named sibling member, so each must be less than the sibling's element count.
consteval detail::IndexesOptionalSpec	wowlib::formats::indexesOptional (std::string_view name)
	Declare a referential contract that tolerates the "none" sentinel: like indexes, except an element that is negative (signed lookup) or all-ones (an unsigned -1, e.g.
consteval detail::IndexesInRootSpec	wowlib::formats::indexesInRoot (std::string_view name)
	Declare a cross-entity referential contract: every element of this (integral) vector member is an index into the named member of the ASSEMBLY's root entity (a WMO group's lightRefs into the root's lights).
consteval detail::ExpectedValueSpec	wowlib::formats::expectedValue (std::uint32_t value)
	Declare an exact-value contract on an integral data member (format version fields: WMO MVER is always 17).

Variables
constexpr detail::OptionalSpec	wowlib::formats::Optional {}
	Mark a chunk member the format does not require: absence on read is fine.
constexpr detail::HeaderSpec	wowlib::formats::Header {}
	Mark a member as a container payload's raw header prelude (e.g.
constexpr detail::ContainerSpec	wowlib::formats::Container {}
	Mark a chunk member whose payload is itself a chunk stream (e.g.
constexpr detail::RepeatingSpec	wowlib::formats::Repeating {}
	Mark a chunk that appears once PER ELEMENT of a std::vector<Element> member, any number of times: each encounter appends one element (whole payload -> element), and each element writes back as its own chunk — unlike a plain vector member, whose single chunk payload is the whole array.
constexpr detail::SequenceDataSpec	wowlib::formats::SequenceData {}
	Mark an offset-entity member (a nested std::vector<std::vector<T>>, one inner array per animation sequence) whose inner data may live in an external buffer — M2 low-priority sequences store their track data in .anim files.
constexpr detail::NonemptySpec	wowlib::formats::Nonempty {}
	Declare a presence contract: the member must hold data for the file to be meaningful to the client, even though read() tolerates its absence (a required-content marker for optional-on-read chunks).

Detailed Description

The chunk annotation vocabulary format entities declare their binary mapping with.

Follows welder's pattern: structural *_spec payloads in detail, consteval factories / inline constants as the user-facing spelling.

Usage (a chunked entity). The canonical order is: chunk() first; then the format annotations (since/until, optional/header/container, repeats); then welder's annotations, with welder::doc always last (a raw string literal when it spans several lines):

template <ClientVersion V>
struct WMORoot : ChunkedFile<WMORoot<V>>
{
  static constexpr ClientVersion version = V;
 
  [[=chunk("MVER")]]
  std::uint32_t mver = 17;
 
  [[
    =chunk("MODI"),
    =since(builds::BfA_TidesOfVengeance),
    =formats::optional,
    =welder::mark::no_reassign,
    =welder::doc("Doodad FileDataIDs (MODI, 8.1+).")]]
  std::vector<std::uint32_t> doodadFdids;
 
  [[=chunk("MOGP"), =container]]
  WMOGroupBody<V> body;
};

Annotations appear only on entity primary-template members, with non-dependent arguments (a member's since()/until() carries the exact client version the chunk appeared/vanished at, as wowdev.wiki documents it, spelled through the named build constants of core/client_builds.hpp) — binary structs carry none. The serializer and the bindings read the same specs, so version activity has a single source of truth.

Definition in file annotations.hpp.