porytiles::Schema Class Reference

A validated metatile attribute layout: an ordered set of non-overlapping fields. More...

#include <metatile_attribute_schema.hpp>

Public Member Functions
const std::vector< Field > &	fields () const
const std::vector< Field > &	value_fields () const
	Returns the fields that hold plain per-metatile values, excluding the layer_type-role field.
std::size_t	attribute_bytes () const
const Field *	layer_type_field () const
	Returns the field carrying the layer_type role, or nullptr when the layer type is disabled.
std::uint32_t	layer_type_mask () const
	Returns the mask of the layer_type bits within the packed attribute word.
std::uint32_t	layer_type_offset () const
	Returns the bit offset of the layer_type's least-significant bit.

Static Public Member Functions
static ChainableResult< Schema >	create (std::vector< Field > fields, std::size_t attribute_bytes)
	Validates a set of fields against an attribute size and builds a Schema.

Detailed Description

A validated metatile attribute layout: an ordered set of non-overlapping fields.

A Schema is the single source of truth for how a packed attribute word is laid out. It owns the fields that make up an attribute word and the byte size those fields were validated against. Schemas can only be built through Schema::create, which enforces the layout rules, so any Schema in hand is known to be well-formed: every field has a contiguous non-zero mask that fits the attribute size, no two fields overlap, no name repeats, and every default fits its field.

The layer type is an ordinary field carrying FieldRole::layer_type (see FieldRole). At most one field may carry the role, and a schema without one has the layer type disabled: every metatile reads back as LayerType::normal and no layer-type bits are packed. The role field's per-metatile value is managed by Porytiles (compile-time inference or a CSV pin), so it is excluded from value_fields(), the field list the attributes CSV columns are built from.

Definition at line 335 of file metatile_attribute_schema.hpp.

Member Function Documentation

attribute_bytes()

std::size_t porytiles::Schema::attribute_bytes ( ) const

inline

Definition at line 373 of file metatile_attribute_schema.hpp.

create()

ChainableResult< Schema > porytiles::Schema::create ( std::vector< Field >  fields, std::size_t  attribute_bytes  )

static

Validates a set of fields against an attribute size and builds a Schema.

Runs a single fail-fast pass over the fields in the given order. For each field the name checks run first (duplicate name, name in the reserved pin_column_prefix namespace), then the intra-field rules (zero mask, non-contiguous mask, mask beyond the attribute size, default value too large), then the layer_type-role rules (at most one role field; no provider or default on it), then the cross-field overlap check against the fields already seen. The first violation wins and is returned as the error; on success the fields are stored in the order given.

Parameters

fields	The fields making up the layout, in the order they should be preserved
attribute_bytes	The attribute size in bytes the layout is validated against

Precondition

attribute_bytes must be 1, 2, or 4.

Returns

A validated Schema, or an error describing the first layout rule violation

Definition at line 50 of file metatile_attribute_schema.cpp.

fields()

const std::vector< Field > & porytiles::Schema::fields ( ) const

inline

Definition at line 353 of file metatile_attribute_schema.hpp.

layer_type_field()

const Field * porytiles::Schema::layer_type_field ( ) const

inline

Returns the field carrying the layer_type role, or nullptr when the layer type is disabled.

Returns

A pointer to the role field within fields(), or nullptr when no field carries the role

Definition at line 381 of file metatile_attribute_schema.hpp.

layer_type_mask()

std::uint32_t porytiles::Schema::layer_type_mask ( ) const

inline

Returns the mask of the layer_type bits within the packed attribute word.

This is the mask of the field carrying FieldRole::layer_type. A returned value of 0 means no field carries the role, so the layer type is disabled: no bits are packed and every metatile decodes as LayerType::normal.

Returns

The layer_type-role field's mask, or 0 when the layer type is disabled

Definition at line 394 of file metatile_attribute_schema.hpp.

layer_type_offset()

std::uint32_t porytiles::Schema::layer_type_offset ( ) const

inline

Returns the bit offset of the layer_type's least-significant bit.

Meaningful only when layer_type_mask() is non-zero. For a disabled (zero) mask the offset is not used: the binary pack/unpack skips the layer type entirely.

Returns

The number of low-order zero bits in layer_type_mask()

Definition at line 406 of file metatile_attribute_schema.hpp.

value_fields()

const std::vector< Field > & porytiles::Schema::value_fields ( ) const

inline

Returns the fields that hold plain per-metatile values, excluding the layer_type-role field.

This is the field list the attributes CSV is built from: one value column per entry, in schema order. The layer_type role field never appears here because its values are managed by Porytiles (compile-time inference or a CSV pin through the separate trailing "pin::layer_type" column), not entered as a value column. Code that renders, parses, or defaults per-field values should iterate this list; code that needs the full packed layout (binary pack/unpack, schema dumps) iterates fields().

Returns

The non-role fields, in schema order

Definition at line 368 of file metatile_attribute_schema.hpp.

---

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

• porytiles/include/porytiles/domain/models/metatile_attribute_schema.hpp
• porytiles/lib/domain/models/metatile_attribute_schema.cpp