Geometry Types

Introduction

Alignment

Alignment is the safe value object for text and graphics alignment. Use it in public APIs when callers should choose at most one horizontal and at most one vertical alignment.

The default value is Alignment::TopLeft. You can also pass one of the predefined constants, such as Alignment::Center or Alignment::BottomRight.

Anchor

Anchor selects a corner, edge, or center of any two-dimensional area. It is appropriate for resolving a relative position in rectangles, sizes, grids, and other geometry types. Unlike Alignment, it describes the position to select rather than how content should be arranged.

Axis Mapper

AxisMapper applies an exact one-, two-, or three-dimensional axis mapping to a compatible geometry value. An unsigned mapping only permutes axes; a signed mapping can also reverse each selected component.

Orientation

Orientation selects a horizontal or vertical main axis. It is useful for describing the layout direction of text or graphics content without implying a direction reversal.

Basic Usage

Construct an alignment from a predefined constant whenever possible:

auto titleAlignment = el::geometry::Alignment::Center;
auto iconAlignment = el::geometry::Alignment::BottomRight;

When a lower-level flag set is used, Alignment normalizes it. If more than one horizontal flag is set, the first one in the order Left, HCenter, Right is kept. If more than one vertical flag is set, the first one in the order Top, VCenter, Bottom is kept.

Optional Axes

Horizontal and vertical components are optional. This is useful when you want to pass only one axis to a lower-level operation:

auto verticalOnly = el::Alignment{el::AlignmentFlag::VCenter};

Use horizontal() and vertical() to extract the individual components. Use toRawValue() when you need the underlying AlignmentFlags value.

Anchor Positions

Construct an Anchor from a predefined constant when a position on a two-dimensional area is needed:

auto anchor = el::geometry::Anchor::BottomRight;

The AnchorFlag and AnchorFlags types support lower-level flag composition before an Anchor normalizes conflicting selections. Horizontal and vertical components are optional, and horizontal() and vertical() return either component alone.

Axis Mapping

Axis names the physical X, Y, and Z axes. AxisMapping specifies the source axis used for each destination axis. Its constructor arity declares the dimensionality and its axes must be an exact permutation for that dimensionality.

Use AxisMapper to apply the mapping to any AxisMappable value:

const auto mapper = el::geometry::AxisMapper{
    el::geometry::AxisMapping{el::geometry::Axis::Y, el::geometry::Axis::X}};
const auto mapped = mapper.map(el::block::Position{10, 20}); // (20, 10)

The orientation constructor is a two-dimensional convenience mapping. Horizontal orientation preserves X/Y order and vertical orientation exchanges X and Y.

Signed Axis Mapping

SignedAxisMapping additionally describes direction reversal with SignedAxis. The mapped value defines reversal semantics for its component type: positions negate coordinates, sizes preserve their non-negative extents, rectangles reflect their half-open coordinate spans, and margins exchange leading and trailing sides.

Mappings reject duplicate, missing, or out-of-range axes. AxisMapper::map() also rejects a value whose declared dimensionality differs from the mapping instead of filling or discarding components.

Alignment Flags

AlignmentFlag contains the low-level bits used to describe horizontal and vertical alignment. Most user-facing APIs should prefer Alignment, because it normalizes conflicting flags into a valid value object.

Flag Groups

The horizontal flags are Left, HCenter and Right. The vertical flags are Top, VCenter and Bottom. The combined enum entries, such as TopLeft and BottomRight, are convenience values made from one horizontal and one vertical flag.

Use AlignmentFlags when an implementation needs to inspect or combine raw alignment bits before creating an Alignment.

Interface

class Alignment

Alignment of text or graphics.

Compared to the low-level AlignmentFlags, this object is bound to valid states. Horizontal and vertical alignment flags are mutually exclusive but optional. Also, this class is immutable and designed to be used as a function parameter.

See: Geometry Types

Public Functions

constexpr Alignment() noexcept = default: Create a top-left alignment.

inline constexpr Alignment(const AlignmentFlags value) noexcept

Create an alignment from the low-level alignment flags.

Ensures that only one horizontal and one vertical flag are set.

bool operator==(const Alignment&) const noexcept = default: Test if two alignments are equal.

bool operator!=(const Alignment&) const noexcept = default: Test if two alignments are different.

inline constexpr bool isLeft() const noexcept: Test if this alignment is on the left side.

inline constexpr bool isHorizontalCenter() const noexcept: Test if this alignment is horizontally centered.

inline constexpr bool isRight() const noexcept: Test if this alignment is on the right side.

inline constexpr bool isTop() const noexcept: Test if this alignment is at the top.

inline constexpr bool isVerticalCenter() const noexcept: Test if this alignment is vertically centered.

inline constexpr bool isBottom() const noexcept: Test if this alignment is at the bottom.

inline constexpr Alignment horizontal() const noexcept: Extract the horizontal alignment component.

inline constexpr Alignment vertical() const noexcept: Extract the vertical alignment component.

inline std::size_t hash() const noexcept: Get a hash for this alignment.

inline constexpr AlignmentFlags toRawValue() const noexcept: Get the underlying alignment flags.

Public Static Attributes

static const Alignment Left = {AlignmentFlag::Left}: Aligned to the left edge of the box.

static const Alignment HCenter = {AlignmentFlag::HCenter}: Aligned to the horizontal center of the box.

static const Alignment Right = {AlignmentFlag::Right}: Aligned to the right edge of the box.

static const Alignment Top = {AlignmentFlag::Top}: Aligned to the top edge of the box.

static const Alignment VCenter = {AlignmentFlag::VCenter}: Aligned to the vertical center of the box.

static const Alignment Bottom = {AlignmentFlag::Bottom}: Aligned to the bottom edge of the box.

static const Alignment TopLeft = {AlignmentFlag::TopLeft}: Aligned to the top-left corner of the box.

static const Alignment TopCenter = {AlignmentFlag::TopCenter}: Aligned to the top-center of the box.

static const Alignment TopRight = {AlignmentFlag::TopRight}: Aligned to the top-right corner of the box.

static const Alignment CenterLeft = {AlignmentFlag::CenterLeft}: Aligned to the center-left of the box.

static const Alignment Center = {AlignmentFlag::Center}: Aligned to the center of the box.

static const Alignment CenterRight = {AlignmentFlag::CenterRight}: Aligned to the center-right of the box.

static const Alignment BottomLeft = {AlignmentFlag::BottomLeft}: Aligned to the bottom-left corner of the box.

static const Alignment BottomCenter = {AlignmentFlag::BottomCenter}: Aligned to the bottom-center of the box.

static const Alignment BottomRight = {AlignmentFlag::BottomRight}: Aligned to the bottom-right corner of the box.

enum class erbsland::geometry::AlignmentFlag : uint8_t

Low-level flags for alignments.

See: Geometry Types

Values:

enumerator None

enumerator Left: Aligned to the left edge.

enumerator HCenter: Aligned to the horizontal center.

enumerator Right: Aligned to the right edge.

enumerator Top: Aligned to the top edge.

enumerator VCenter: Aligned to the vertical center.

enumerator Bottom: Aligned to the bottom edge.

enumerator TopLeft

enumerator TopCenter

enumerator TopRight

enumerator CenterLeft

enumerator Center

enumerator CenterRight

enumerator BottomLeft

enumerator BottomCenter

enumerator BottomRight

enumerator HorizontalMask

enumerator VerticalMask

enumerator All

using erbsland::geometry::AlignmentFlags = util::EnumFlags<AlignmentFlag>: Low-level alignment flags.

class Anchor

Selects a relative position in a two-dimensional area.

An anchor contains at most one horizontal and one vertical component. It is suitable for choosing a corner, edge, or center when positioning geometry or resolving a value from a two-dimensional grid.

See: Geometry Types

Public Functions

constexpr Anchor() noexcept = default: Create a top-left anchor.

inline constexpr Anchor(const AnchorFlags value) noexcept

Create an anchor from low-level flags.

If multiple flags select the same axis, the first one in left/center/right or top/center/bottom order is kept.

Parameters:: value – The flags that select the anchor components.

Anchor &operator=(const Anchor&) = default: Assign an anchor.

bool operator==(const Anchor&) const noexcept = default: Test two anchors for equality.

bool operator!=(const Anchor&) const noexcept = default: Test two anchors for inequality.

inline constexpr bool isLeft() const noexcept: Test whether this anchor selects the left edge.

inline constexpr bool isHorizontalCenter() const noexcept: Test whether this anchor selects the horizontal center.

inline constexpr bool isRight() const noexcept: Test whether this anchor selects the right edge.

inline constexpr bool isTop() const noexcept: Test whether this anchor selects the top edge.

inline constexpr bool isVerticalCenter() const noexcept: Test whether this anchor selects the vertical center.

inline constexpr bool isBottom() const noexcept: Test whether this anchor selects the bottom edge.

inline constexpr Anchor horizontal() const noexcept: Return only the horizontal component.

inline constexpr Anchor vertical() const noexcept: Return only the vertical component.

inline std::size_t hash() const noexcept: Create a hash value for this anchor.

inline constexpr AnchorFlags toRawValue() const noexcept: Return the normalized low-level flags.

Public Static Attributes

static const Anchor Left = {AnchorFlag::Left}: The left edge.

static const Anchor HCenter = {AnchorFlag::HCenter}: The horizontal center.

static const Anchor Right = {AnchorFlag::Right}: The right edge.

static const Anchor Top = {AnchorFlag::Top}: The top edge.

static const Anchor VCenter = {AnchorFlag::VCenter}: The vertical center.

static const Anchor Bottom = {AnchorFlag::Bottom}: The bottom edge.

static const Anchor TopLeft = {AnchorFlag::TopLeft}: The top-left corner.

static const Anchor TopCenter = {AnchorFlag::TopCenter}: The top-center edge.

static const Anchor TopRight = {AnchorFlag::TopRight}: The top-right corner.

static const Anchor CenterLeft = {AnchorFlag::CenterLeft}: The center-left edge.

static const Anchor Center = {AnchorFlag::Center}: The center.

static const Anchor CenterRight = {AnchorFlag::CenterRight}: The center-right edge.

static const Anchor BottomLeft = {AnchorFlag::BottomLeft}: The bottom-left corner.

static const Anchor BottomCenter = {AnchorFlag::BottomCenter}: The bottom-center edge.

static const Anchor BottomRight = {AnchorFlag::BottomRight}: The bottom-right corner.

Friends

inline friend constexpr Anchor operator|(Anchor lhs, Anchor rhs) noexcept

Combine axis components from two anchors.

Conflicting components are normalized using the same priority as the flag constructor.

enum class erbsland::geometry::AnchorFlag : uint8_t

Low-level flags that select a position in a two-dimensional area.

See: Geometry Types

Values:

enumerator None: Do not select an axis component.

enumerator Top: Select the top edge.

enumerator VCenter: Select the vertical center.

enumerator Bottom: Select the bottom edge.

enumerator Left: Select the left edge.

enumerator HCenter: Select the horizontal center.

enumerator Right: Select the right edge.

enumerator TopLeft: Select the top-left corner.

enumerator TopCenter: Select the top-center edge.

enumerator TopRight: Select the top-right corner.

enumerator CenterLeft: Select the center-left edge.

enumerator Center: Select the center.

enumerator CenterRight: Select the center-right edge.

enumerator BottomLeft: Select the bottom-left corner.

enumerator BottomCenter: Select the bottom-center edge.

enumerator BottomRight: Select the bottom-right corner.

enumerator HorizontalMask: Select all horizontal flags.

enumerator VerticalMask: Select all vertical flags.

enumerator All: Select every anchor flag.

using erbsland::geometry::AnchorFlags = util::EnumFlags<AnchorFlag>: A set of low-level anchor flags.

enum class erbsland::geometry::Axis : uint8_t

A physical geometry axis.

Values:

enumerator X: The x-axis.

enumerator Y: The y-axis.

enumerator Z: The z-axis.

template<typename T> concept AxisMappable: #include <erbsland/geometry/AxisMappable.hpp>

A geometry value that can be reconstructed from mapped axis components.

class AxisMapper

Applies an exact axis permutation and direction mapping to geometry values.

See: Geometry Types

Public Functions

inline explicit constexpr AxisMapper(const Orientation orientation) noexcept

Create a two-dimensional mapper with the specified main-axis orientation.

Parameters:: orientation – The orientation of the main axis.

inline explicit constexpr AxisMapper(const AxisMapping mapping)

Create a mapper from an unsigned axis mapping.

Parameters:: mapping – The unsigned mapping to use.

inline explicit constexpr AxisMapper(const SignedAxisMapping mapping) noexcept

Create a mapper from a signed axis mapping.

Parameters:: mapping – The signed mapping to use.

inline constexpr Dimensionality dimensionality() const noexcept: Get the dimensionality required by this mapper.

inline constexpr const SignedAxisMapping &mapping() const noexcept: Get the canonical signed mapping.

template<AxisMappable T> inline constexpr T map(T value) const

Map the axes of a geometry value.

Template Parameters:: T – The geometry value type.
Parameters:: value – The value to map.
Throws:: err::ParameterError – if the value and mapping dimensionalities differ.
Returns:: The reconstructed mapped value.

class AxisMapping

An exact permutation of one, two, or three physical axes.

Constructor arguments specify the source axis used for each destination axis in x/y/z order.

See: Geometry Types

Public Functions

inline explicit constexpr AxisMapping(Axis x)

Create a one-dimensional mapping.

Parameters:: x – The source axis for destination X.
Throws:: err::ParameterError – if x is not X.

inline constexpr AxisMapping(Axis x, Axis y)

Create a two-dimensional mapping.

Parameters:

x – The source axis for destination X.
y – The source axis for destination Y.

Throws:

err::ParameterError – if the axes are not an exact X/Y permutation.

inline constexpr AxisMapping(Axis x, Axis y, Axis z)

Create a three-dimensional mapping.

Parameters:

x – The source axis for destination X.
y – The source axis for destination Y.
z – The source axis for destination Z.

Throws:

err::ParameterError – if the axes are not an exact X/Y/Z permutation.

inline explicit constexpr AxisMapping(const Orientation orientation) noexcept

Create a two-dimensional mapping from a main-axis orientation.

Horizontal orientation creates the identity; vertical orientation exchanges X and Y.

Parameters:: orientation – The main-axis orientation.

bool operator==(const AxisMapping&) const noexcept = default: Compare two mappings.

bool operator!=(const AxisMapping&) const noexcept = default: Compare two mappings.

inline constexpr bool isIdentity() const noexcept: Test whether this mapping preserves every active axis.

inline constexpr Dimensionality dimensionality() const noexcept: Get the dimensionality declared by this mapping.

inline constexpr Axis source(const Axis destination) const

Get the source axis used for a destination axis.

Parameters:: destination – The destination axis to inspect.
Throws:: err::ParameterError – if destination is outside this mapping’s dimensionality.
Returns:: The source axis for destination.

enum class erbsland::geometry::Dimensionality : uint8_t

The number of spatial dimensions represented by a geometry value.

Values:

enumerator One: One-dimensional geometry.

enumerator Two: Two-dimensional geometry.

enumerator Three: Three-dimensional geometry.

class Orientation

Represents the orientation of a layout or a direction.

See: Geometry Types

Public Types

enum Value

The stored orientation value.

Values:

enumerator Horizontal: Horizontal orientation, e.g. for horizontal layouts or horizontal scrolling.

enumerator Vertical: Vertical orientation, e.g. for vertical layouts or vertical scrolling.

Public Functions

constexpr Orientation() noexcept = default: Construct the default horizontal orientation.

inline constexpr Orientation(const Value value) noexcept

Construct an orientation from a value.

Parameters:: value – The orientation value.

bool operator==(const Orientation &other) const noexcept = default: Equality comparison.

bool operator!=(const Orientation &other) const noexcept = default: Inequality comparison.

inline constexpr Value value() const noexcept

Get the stored value.

Returns:: The wrapped orientation value.

inline constexpr Orientation crossed() const noexcept

Get the crossed orientation.

Returns:: Vertical for Horizontal, otherwise Horizontal.

class SignedAxis

A physical geometry axis with an optional direction reversal.

See: Geometry Types

Public Types

enum Value

The signed-axis values.

Values:

enumerator PositiveX: The positive x-axis.

enumerator PositiveY: The positive y-axis.

enumerator PositiveZ: The positive z-axis.

enumerator NegativeX: The reversed x-axis.

enumerator NegativeY: The reversed y-axis.

enumerator NegativeZ: The reversed z-axis.

Public Functions

constexpr SignedAxis() noexcept = default: Create the positive x-axis.

inline constexpr SignedAxis(const Value value) noexcept

Create a signed axis from a value.

Parameters:: value – The signed-axis value.

inline constexpr SignedAxis(const Axis axis) noexcept

Create a positive signed axis from a physical axis.

Parameters:: axis – The physical axis.

bool operator==(const SignedAxis&) const noexcept = default: Compare two signed axes.

bool operator!=(const SignedAxis&) const noexcept = default: Compare two signed axes.

inline constexpr bool isValid() const noexcept: Test whether the stored value is a defined signed axis.

inline constexpr bool isReversed() const noexcept: Test whether this axis reverses its component.

inline constexpr Axis axis() const noexcept: Get the physical axis without its direction.

inline constexpr Value value() const noexcept: Get the stored value.

class SignedAxisMapping

An exact axis permutation with independent direction reversal for every destination axis.

Constructor arguments specify the signed source axis used for each destination axis in x/y/z order.

See: Geometry Types

Public Functions

inline explicit constexpr SignedAxisMapping(SignedAxis x)

Create a one-dimensional signed mapping.

Parameters:: x – The signed source axis for destination X.
Throws:: err::ParameterError – if x does not select X.

inline constexpr SignedAxisMapping(SignedAxis x, SignedAxis y)

Create a two-dimensional signed mapping.

Parameters:

x – The signed source axis for destination X.
y – The signed source axis for destination Y.

Throws:

err::ParameterError – if the axes are not an exact X/Y permutation.

inline constexpr SignedAxisMapping(SignedAxis x, SignedAxis y, SignedAxis z)

Create a three-dimensional signed mapping.

Parameters:

x – The signed source axis for destination X.
y – The signed source axis for destination Y.
z – The signed source axis for destination Z.

Throws:

err::ParameterError – if the axes are not an exact X/Y/Z permutation.

inline constexpr SignedAxisMapping(const AxisMapping mapping)

Create an all-positive signed mapping from an unsigned mapping.

Parameters:: mapping – The source mapping.

bool operator==(const SignedAxisMapping&) const noexcept = default: Compare two mappings.

bool operator!=(const SignedAxisMapping&) const noexcept = default: Compare two mappings.

inline constexpr bool isIdentity() const noexcept: Test whether this mapping preserves every active axis and direction.

inline constexpr Dimensionality dimensionality() const noexcept: Get the dimensionality declared by this mapping.

inline constexpr SignedAxis source(const Axis destination) const

Get the signed source axis used for a destination axis.

Parameters:: destination – The destination axis to inspect.
Throws:: err::ParameterError – if destination is outside this mapping’s dimensionality.
Returns:: The signed source axis for destination.

enum class erbsland::geometry::Symmetry : uint8_t

Symmetry transforms for positions in a block size or rectangle.

Values:

enumerator Identity: Keep the position unchanged.

enumerator Rotate90: Rotate 90 degrees counter-clockwise.

enumerator Rotate180: Rotate 180 degrees.

enumerator Rotate270: Rotate 270 degrees counter-clockwise.

enumerator MirrorHorizontal: Mirror horizontally, exchanging left and right.

enumerator MirrorVertical: Mirror vertically, exchanging top and bottom.

enumerator MirrorDiagonal: Mirror along the top-left to bottom-right diagonal.

enumerator MirrorAntiDiagonal: Mirror along the top-right to bottom-left diagonal.