z_value_layer_manager.h File Reference

Semantic Z-value layer management for game scene rendering. More...

#include <QtGlobal>

Include dependency graph for z_value_layer_manager.h:

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

Go to the source code of this file.

Namespaces
namespace	ZValueLayerManager
	Utilities for Z-value validation and layer management.

Enumerations
enum class	ZValueLayerManager::Layer { ZValueLayerManager::Zone , ZValueLayerManager::Card , ZValueLayerManager::Overlay }
	Semantic layer identifiers for Z-value allocation. More...

Functions
constexpr bool	ZValueLayerManager::isValidCardZValue (qreal zValue)
	Validates that a Z-value is within the valid card range.
constexpr bool	ZValueLayerManager::isOverlayZValue (qreal zValue)
	Validates that a Z-value is in the overlay layer.
constexpr qreal	ZValueLayerManager::overlayZValue (qreal offset)
	Returns the Z-value for a specific overlay element.

Variables
constexpr qreal	ZValueLayerManager::CARD_Z_VALUE_MAX = 40000000.0
	Maximum Z-value a card can have on the table zone.
constexpr qreal	ZValueLayerManager::OVERLAY_BASE = 2000000000.0
	Base Z-value for overlay elements.

Detailed Description

Semantic Z-value layer management for game scene rendering.

This file provides a structured approach to Z-value allocation in the game scene. Z-values in Qt determine stacking order - higher values render on top of lower values.

Layer Architecture

The game scene is organized into three conceptual layers:

1. Zone Layer (0-999): Zone backgrounds, containers, and static elements
   • Zone backgrounds (0.5-1.0)
   • Cards within zones (1.0 base + index)
2. Card Layer (1-40,000,000): Dynamic card rendering on the table zone
   • Cards use formula: (actualY + CARD_HEIGHT) * 100000 + (actualX + 1) * 100
   • Maximum card Z-value: ~40,000,000 (with 3 rows, actualY <= ~289)
3. Overlay Layer (2,000,000,000+): UI elements that must appear above all cards
   • Hovered cards (+1)
   • Arrows (+3)
   • Zone views (+4)
   • Drag items (+5, +6)
   • Top UI elements (+7)

Design Rationale

The large gap between card Z-values (max ~40M) and overlay base (2B) provides safety margin for future table zone expansions while ensuring overlays always render above cards regardless of table position.

Usage

Prefer using the semantic constants from ZValues namespace:

card->setZValue(ZValues::HOVERED_CARD);
arrow->setZValue(ZValues::ARROWS);

Use validation functions to verify card Z-values during development:

Q_ASSERT(ZValueLayerManager::isValidCardZValue(cardZ));