Viewport Class

Represents a rectangular area within a RenderTarget where a scene is rendered. More...

Declaration

class helios::rendering::Viewport { ... }

Public Constructors Index

	Viewport () noexcept
	Constructs a Viewport with normalized bounds set to (0.0f, 0.0f, 1.0f, 1.0f) and z-index 0. More...
	Viewport (float x, float y, float width, float height, const helios::engine::core::data::ViewportId viewportId=helios::engine::core::data::ViewportId{helios::core::types::no_init}, const int zIndex=0) noexcept
	Constructs a Viewport with specified normalized dimensions. More...

Public Member Functions Index

const helios::rendering::RenderTarget *	renderTarget () const noexcept
	Gets the parent RenderTarget. More...
helios::engine::core::data::ViewportId	viewportId () const noexcept
	Returns the unique identifier for this viewport. More...
Viewport &	setCameraSceneNode (helios::scene::CameraSceneNode *cameraSceneNode) noexcept
	Assigns a camera scene node to this viewport. More...
const helios::scene::CameraSceneNode *	cameraSceneNode () const noexcept
	Gets the camera scene node associated with this viewport. More...
Viewport &	setRenderTarget (const helios::rendering::RenderTarget *renderTarget, ViewportKey key) noexcept
	Sets the parent RenderTarget for this viewport. More...
const helios::math::vec4f &	bounds () const noexcept
	Gets the cached dimensions of the viewport. More...
const helios::math::vec4f &	absoluteBounds () const noexcept
	Gets the cached absolute bounds of the viewport in pixels. More...
ViewportSnapshot	snapshot () const noexcept
	Returns an immutable snapshot of this viewport's current state. More...
void	setBounds (float x, float y, float width, float height) noexcept
	Sets the normalized bounds of the viewport. More...
int	clearFlags () const noexcept
	Gets the clear flags for this viewport. More...
const helios::math::vec4f &	clearColor () const noexcept
	Gets the color used for clearing the color buffer. More...
Viewport &	setClearFlags (int clearFlags) noexcept
	Sets the clear flags for this viewport. More...
Viewport &	setClearColor (const helios::math::vec4f &color) noexcept
	Specifies the RGBA values used when clearing color buffers. More...
Viewport &	setZIndex (int zIndex) noexcept
	Sets the z-index that controls rendering order relative to sibling viewports. More...
void	onRenderTargetResize (const unsigned int width, const unsigned int height) noexcept
	Notifies the viewport of a change in the parent RenderTarget's dimensions. More...

Private Member Functions Index

void	updateCache () const noexcept
	Updates the cached dimensions vector if it is dirty. More...
void	updateCamera (unsigned int renderTargetWidth, unsigned int renderTargetHeight) noexcept
	Updates this Viewport's CameraSceneNode and its associated Camera based on the dimension of the RenderTarget. More...

Private Member Attributes Index

const helios::rendering::RenderTarget *	renderTarget_ = nullptr
	Pointer to the parent RenderTarget. More...
int	clearFlags_ = std::to_underlying(ClearFlags::Color)
	Bitmask of buffers to clear. More...
helios::math::vec4f	clearColor_ = helios::math::vec4f(0.0f, 0.0f, 0.0f, 1.0f)
	Color used when clearing the color buffer. Defaults to "black", i.e. no color at all. More...
float	x_ = 0.0f
	The x-offset of the viewport, normalized to [0, 1]. More...
float	y_ = 0.0f
	The y-offset of the viewport, normalized to [0, 1]. More...
float	width_ = 1.0f
	The width of the viewport, normalized to [0, 1]. More...
float	height_ = 1.0f
	The height of the viewport, normalized to [0, 1]. More...
helios::math::vec2ui	renderTargetSize_ {}
	Size of the parent RenderTarget in pixels. More...
helios::scene::CameraSceneNode *	cameraSceneNode_ = nullptr
	The cameraSceneNode associated as the main camera with this viewport. More...
bool	needsUpdate_ = true
	Flag indicating if cached dimensions are dirty. More...
helios::math::vec4f	bounds_
	Cached dimensions [x, y, width, height]. More...
int	zIndex_ = 0
	The z-index for this viewport. More...
const helios::engine::core::data::ViewportId	viewportId_ {helios::core::types::no_init}
	Unique identifier for this viewport. More...
helios::math::vec4f	absoluteBounds_ {}
	Cached absolute bounds [x, y, width, height] in pixels. More...
ViewportSnapshot	snapshot_ {}
	Cached viewport snapshot for efficient access. More...

Private Static Attributes Index

static const helios::util::log::Logger &	logger_ = helios::util::log::LogManager::loggerForScope(HELIOS_LOG_SCOPE)

Description

Represents a rectangular area within a RenderTarget where a scene is rendered.

A Viewport defines the 2D rectangle into which a 3D scene is projected. Its dimensions are specified in normalized coordinates relative to its parent `RenderTarget`. It is associated with a `CameraSceneNode`, which provides the view and projection matrices. The viewport automatically updates the CameraSceneNode associated camera's aspect ratio when its parent `RenderTarget` is resized.

Since a Viewport only stores normalized values for its location and dimensions relative to the owning RenderTarget, rendering APIs should query the size of the RenderTarget when a viewport is about to be rendered, allowing them to compute the final screen coordinates and dimensions correctly.

See Also

helios::rendering::RenderTarget

See Also

helios::scene::CameraSceneNode

See Also

https://registry.khronos.org/OpenGL-Refpages/gl4/html/glViewport.xhtml

Definition at line 64 of file Viewport.ixx.

Public Constructors

Viewport()

helios::rendering::Viewport::Viewport ()

inline noexcept

Constructs a Viewport with normalized bounds set to (0.0f, 0.0f, 1.0f, 1.0f) and z-index 0.

Definition at line 200 of file Viewport.ixx.

200 Viewport() noexcept : x_(0.0f), y_(0.0f), width_(1.0f), height_(1.0f), zIndex_(0) {

201 needsUpdate_ = true;

202 }

Referenced by setCameraSceneNode, setClearColor, setClearFlags, setRenderTarget and setZIndex.

Viewport()

helios::rendering::Viewport::Viewport (float x, float y, float width, float height, const helios::engine::core::data::ViewportId viewportId=helios::engine::core::data::ViewportId{helios::core::types::no_init}, const int zIndex=0)

inline explicit noexcept

Constructs a Viewport with specified normalized dimensions.

Parameters

x	The normalized horizontal offset [0, 1].
y	The normalized vertical offset [0, 1].
width	The normalized width [0, 1].
height	The normalized height [0, 1].
zIndex	The z-index that determines the rendering order.

Definition at line 213 of file Viewport.ixx.

213 explicit Viewport(

214 float x, float y, float width, float height,

215 const helios::engine::core::data::ViewportId viewportId = helios::engine::core::data::ViewportId{helios::core::types::no_init},

216 const int zIndex = 0

217 ) noexcept

218 :

219 viewportId_(viewportId),

220 zIndex_(zIndex) {

221 setBounds(x, y, width, height);

222 }

References helios::core::types::no_init and viewportId.

Public Member Functions

absoluteBounds()

const helios::math::vec4f & helios::rendering::Viewport::absoluteBounds ()

inline nodiscard noexcept

Gets the cached absolute bounds of the viewport in pixels.

Returns

A const reference to a vec4f containing [x, y, width, height] in pixels.

Definition at line 305 of file Viewport.ixx.

305 [[nodiscard]] const helios::math::vec4f& absoluteBounds() const noexcept {

306 updateCache();

307 return absoluteBounds_;

308 }

bounds()

const helios::math::vec4f & helios::rendering::Viewport::bounds ()

inline nodiscard noexcept

Gets the cached dimensions of the viewport.

Returns

A const reference to a vec4f containing [x, y, width, height].

Definition at line 295 of file Viewport.ixx.

295 [[nodiscard]] const helios::math::vec4f& bounds() const noexcept {

296 updateCache();

297 return bounds_;

298 }

cameraSceneNode()

const helios::scene::CameraSceneNode * helios::rendering::Viewport::cameraSceneNode ()

inline nodiscard noexcept

Gets the camera scene node associated with this viewport.

Returns

A const pointer to the associated `CameraSceneNode`, or `nullptr` if none is set.

Definition at line 266 of file Viewport.ixx.

266 [[nodiscard]] const helios::scene::CameraSceneNode* cameraSceneNode() const noexcept {

267 return cameraSceneNode_;

268 }

Referenced by helios::scene::Scene::createSnapshot and setCameraSceneNode.

clearColor()

const helios::math::vec4f & helios::rendering::Viewport::clearColor ()

inline nodiscard noexcept

Gets the color used for clearing the color buffer.

Returns

A const reference to the clear color.

Definition at line 363 of file Viewport.ixx.

363 [[nodiscard]] const helios::math::vec4f& clearColor() const noexcept {

364 return clearColor_;

365 }

clearFlags()

int helios::rendering::Viewport::clearFlags ()

inline nodiscard noexcept

Gets the clear flags for this viewport.

Returns

An integer bitmask representing the `ClearFlags`.

Definition at line 354 of file Viewport.ixx.

354 [[nodiscard]] int clearFlags() const noexcept {

355 return clearFlags_;

356 }

Referenced by setClearFlags.

onRenderTargetResize()

void helios::rendering::Viewport::onRenderTargetResize (const unsigned int width, const unsigned int height)

inline noexcept

Notifies the viewport of a change in the parent RenderTarget's dimensions.

This method is called by the parent `RenderTarget` when it is resized. The viewport uses the new dimensions to calculate the correct aspect ratio for its associated camera.

Parameters

width	The new width of the RenderTarget in pixels.
height	The new height of the RenderTarget in pixels.

See Also

updateCamera()

Definition at line 417 of file Viewport.ixx.

417 void onRenderTargetResize(const unsigned int width, const unsigned int height) noexcept {

418 renderTargetSize_ = {width, height};

419 needsUpdate_ = true;

420 updateCamera(width, height);

421 }

renderTarget()

const helios::rendering::RenderTarget * helios::rendering::Viewport::renderTarget ()

inline nodiscard noexcept

Gets the parent RenderTarget.

If the returned value is a nullptr, this Viewport is not owned by any RenderTarget.

Returns

A const pointer to the parent RenderTarget, or `nullptr` if not set.

Definition at line 231 of file Viewport.ixx.

231 [[nodiscard]] const helios::rendering::RenderTarget* renderTarget() const noexcept {

232 return renderTarget_;

233 }

Referenced by setRenderTarget.

setBounds()

void helios::rendering::Viewport::setBounds (float x, float y, float width, float height)

inline noexcept

Sets the normalized bounds of the viewport.

Parameters

x	The normalized horizontal offset [0, 1].
y	The normalized vertical offset [0, 1].
width	The normalized width [0, 1].
height	The normalized height [0, 1].

Definition at line 333 of file Viewport.ixx.

333 void setBounds(

334 float x, float y, float width, float height

335 ) noexcept {

336 x_ = x;

337 y_ = y;

338 width_ = width;

339 height_ = height;

340

341 needsUpdate_ = true;

342

343 assert((x_ >= 0.0f && x_ <= 1.0f) && "setBounds received unexpected value for x");

344 assert((y_ >= 0.0f && y_ <= 1.0f) && "setBounds received unexpected value for y");

345 assert((width_ >= 0.0f && width_ <= 1.0f) && "setBounds received unexpected value for width");

346 assert((height_ >= 0.0f && height_ <= 1.0f) && "setBounds received unexpected value for height");

347 }

setCameraSceneNode()

Viewport & helios::rendering::Viewport::setCameraSceneNode (helios::scene::CameraSceneNode * cameraSceneNode)

inline noexcept

Assigns a camera scene node to this viewport.

The viewport uses the associated camera's projection matrix and the node's computed view matrix for rendering. The camera's aspect ratio is automatically updated when the parent RenderTarget is resized.

Parameters

cameraSceneNode

A non-owning raw pointer to the `CameraSceneNode`. Must remain valid for the lifetime of this viewport.

Returns

A reference to this viewport to allow fluent chaining.

Definition at line 256 of file Viewport.ixx.

256 Viewport& setCameraSceneNode(helios::scene::CameraSceneNode* cameraSceneNode) noexcept {

257 cameraSceneNode_ = cameraSceneNode;

258 return *this;

259 }

References cameraSceneNode and Viewport.

setClearColor()

Viewport & helios::rendering::Viewport::setClearColor (const helios::math::vec4f & color)

inline noexcept

Specifies the RGBA values used when clearing color buffers.

Values are automatically clamped to the range [0, 1].

Parameters

color

The color to use for clearing.

Returns

A reference to this viewport to allow fluent chaining.

Definition at line 388 of file Viewport.ixx.

388 Viewport& setClearColor(const helios::math::vec4f& color) noexcept {

389 clearColor_ = color;

390 return *this;

391 }

Reference Viewport.

setClearFlags()

Viewport & helios::rendering::Viewport::setClearFlags (int clearFlags)

inline noexcept

Sets the clear flags for this viewport.

Parameters

clearFlags

An integer bitmask created from `ClearFlags` enum values.

Returns

A reference to this viewport to allow fluent chaining.

Definition at line 374 of file Viewport.ixx.

374 Viewport& setClearFlags(int clearFlags) noexcept {

375 clearFlags_ = clearFlags;

376 return *this;

377 }

References clearFlags and Viewport.

setRenderTarget()

Viewport & helios::rendering::Viewport::setRenderTarget (const helios::rendering::RenderTarget * renderTarget, ViewportKey key)

inline noexcept

Sets the parent RenderTarget for this viewport.

This function can only be called by classes that can construct a `ViewportKey`, effectively restricting its use to the `RenderTarget` class.

Parameters

renderTarget	A pointer to the parent RenderTarget.
key	A `ViewportKey` instance, required for authorization.

Returns

A reference to this viewport to allow fluent chaining.

See Also

updateCamera()

Todo

The Viewport should observe the RenderTarget for state changes (e.g., resize).

Definition at line 285 of file Viewport.ixx.

285 Viewport& setRenderTarget(const helios::rendering::RenderTarget* renderTarget, ViewportKey key) noexcept {

286 renderTarget_ = renderTarget;

287 return *this;

288 }

References renderTarget and Viewport.

setZIndex()

Viewport & helios::rendering::Viewport::setZIndex (int zIndex)

inline noexcept

Sets the z-index that controls rendering order relative to sibling viewports.

Parameters

zIndex

The new z-index value; higher values are rendered later.

Returns

A reference to this viewport to allow fluent chaining.

Definition at line 400 of file Viewport.ixx.

400 Viewport& setZIndex(int zIndex) noexcept {

401 zIndex_ = zIndex;

402 return *this;

403 }

Reference Viewport.

snapshot()

ViewportSnapshot helios::rendering::Viewport::snapshot ()

inline nodiscard noexcept

Returns an immutable snapshot of this viewport's current state.

The snapshot contains the viewport ID and both normalized and absolute bounds. Useful for passing viewport state to rendering systems without exposing the mutable Viewport object.

Returns

A ViewportSnapshot containing the current viewport state.

Definition at line 319 of file Viewport.ixx.

319 [[nodiscard]] ViewportSnapshot snapshot() const noexcept {

320 updateCache();

321 return snapshot_;

322 }

viewportId()

helios::engine::core::data::ViewportId helios::rendering::Viewport::viewportId ()

inline nodiscard noexcept

Returns the unique identifier for this viewport.

Returns

The ViewportId assigned to this viewport.

Definition at line 240 of file Viewport.ixx.

240 [[nodiscard]] helios::engine::core::data::ViewportId viewportId() const noexcept {

241 return viewportId_;

242 }

Referenced by Viewport.

Private Member Functions

updateCache()

void helios::rendering::Viewport::updateCache ()

inline noexcept

Updates the cached dimensions vector if it is dirty.

Definition at line 145 of file Viewport.ixx.

145 void updateCache() const noexcept {

146

147 if (!needsUpdate_) {

148 return;

149 }

150

151 bounds_[0] = x_;

152 bounds_[1] = y_;

153 bounds_[2] = width_;

154 bounds_[3] = height_;

155

156 absoluteBounds_ = {

157 bounds_[0] * renderTargetSize_[0],

158 bounds_[1] * renderTargetSize_[1],

159 bounds_[2] * renderTargetSize_[0],

160 bounds_[3] * renderTargetSize_[1]

161 };

162

163 snapshot_ = {viewportId_, bounds_, absoluteBounds_};

164

165 needsUpdate_ = false;

166 }

updateCamera()

void helios::rendering::Viewport::updateCamera (unsigned int renderTargetWidth, unsigned int renderTargetHeight)

inline noexcept

Updates this Viewport's CameraSceneNode and its associated Camera based on the dimension of the RenderTarget.

Parameters

width	The new width of the RenderTarget in pixels.
height	The new height of the RenderTarget in pixels.

This method should be called internally whenever the dimensions of the owning RenderTarget change.

Definition at line 182 of file Viewport.ixx.

182 void updateCamera(unsigned int renderTargetWidth, unsigned int renderTargetHeight) noexcept {

183 assert(renderTarget_ && "No RenderTarget available for updateCamera()");

184

185 if (!cameraSceneNode_) {

186 logger_.warn("updateCamera: Viewport was not configured with a CameraSceneNode, nothing to do here.");

187 return;

188 }

189

190 cameraSceneNode_->camera().onResize(

191 static_cast<float>(renderTargetWidth) * width_,

192 static_cast<float>(renderTargetHeight) * height_

193 );

194 }

Private Member Attributes

absoluteBounds_

helios::math::vec4f helios::rendering::Viewport::absoluteBounds_ {}

mutable

Cached absolute bounds [x, y, width, height] in pixels.

Definition at line 140 of file Viewport.ixx.

140 mutable helios::math::vec4f absoluteBounds_{};

bounds_

helios::math::vec4f helios::rendering::Viewport::bounds_

mutable

Cached dimensions [x, y, width, height].

Definition at line 121 of file Viewport.ixx.

121 mutable helios::math::vec4f bounds_;

cameraSceneNode_

helios::scene::CameraSceneNode* helios::rendering::Viewport::cameraSceneNode_ = nullptr

The cameraSceneNode associated as the main camera with this viewport.

Definition at line 111 of file Viewport.ixx.

111 helios::scene::CameraSceneNode* cameraSceneNode_ = nullptr;

clearColor_

helios::math::vec4f helios::rendering::Viewport::clearColor_ = helios::math::vec4f(0.0f, 0.0f, 0.0f, 1.0f)

Color used when clearing the color buffer. Defaults to "black", i.e. no color at all.

Definition at line 83 of file Viewport.ixx.

83 helios::math::vec4f clearColor_ = helios::math::vec4f(0.0f, 0.0f, 0.0f, 1.0f);

clearFlags_

int helios::rendering::Viewport::clearFlags_ = std::to_underlying(ClearFlags::Color)

Bitmask of buffers to clear.

Defaults to ClearFlags::Color.

Definition at line 78 of file Viewport.ixx.

78 int clearFlags_ = std::to_underlying(ClearFlags::Color);

height_

float helios::rendering::Viewport::height_ = 1.0f

The height of the viewport, normalized to [0, 1].

Definition at line 101 of file Viewport.ixx.

101 float height_ = 1.0f;

needsUpdate_

bool helios::rendering::Viewport::needsUpdate_ = true

mutable

Flag indicating if cached dimensions are dirty.

Definition at line 116 of file Viewport.ixx.

116 mutable bool needsUpdate_ = true;

renderTarget_

const helios::rendering::RenderTarget* helios::rendering::Viewport::renderTarget_ = nullptr

Pointer to the parent RenderTarget.

Definition at line 71 of file Viewport.ixx.

71 const helios::rendering::RenderTarget* renderTarget_ = nullptr;

renderTargetSize_

helios::math::vec2ui helios::rendering::Viewport::renderTargetSize_ {}

Size of the parent RenderTarget in pixels.

Definition at line 106 of file Viewport.ixx.

106 helios::math::vec2ui renderTargetSize_{};

snapshot_

ViewportSnapshot helios::rendering::Viewport::snapshot_ {}

mutable

Cached viewport snapshot for efficient access.

Definition at line 171 of file Viewport.ixx.

171 mutable ViewportSnapshot snapshot_{};

viewportId_

const helios::engine::core::data::ViewportId helios::rendering::Viewport::viewportId_ {helios::core::types::no_init}

Unique identifier for this viewport.

Definition at line 135 of file Viewport.ixx.

135 const helios::engine::core::data::ViewportId viewportId_{helios::core::types::no_init};

width_

float helios::rendering::Viewport::width_ = 1.0f

The width of the viewport, normalized to [0, 1].

Definition at line 97 of file Viewport.ixx.

97 float width_ = 1.0f;

x_

float helios::rendering::Viewport::x_ = 0.0f

The x-offset of the viewport, normalized to [0, 1].

Definition at line 88 of file Viewport.ixx.

88 float x_ = 0.0f;

y_

float helios::rendering::Viewport::y_ = 0.0f

The y-offset of the viewport, normalized to [0, 1].

Definition at line 92 of file Viewport.ixx.

92 float y_ = 0.0f;

zIndex_

int helios::rendering::Viewport::zIndex_ = 0

The z-index for this viewport.

The z-index represents the order the Viewport gets rendered. A higher z-index means that the viewport gets rendered after viewports with a lower z-index are rendered.

Definition at line 130 of file Viewport.ixx.

130 int zIndex_ = 0;

Private Static Attributes

logger_

const helios::util::log::Logger& helios::rendering::Viewport::logger_ = helios::util::log::LogManager::loggerForScope(HELIOS_LOG_SCOPE)

static

Definition at line 65 of file Viewport.ixx.

65 inline static const helios::util::log::Logger& logger_ = helios::util::log::LogManager::loggerForScope(HELIOS_LOG_SCOPE);

---

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

• Viewport.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.