Magnum::Ui::AbstractLayer class new in Git master

#include <Magnum/Ui/AbstractLayer.h>

Magnum::Ui::AbstractLayer::AbstractLayer(LayerHandle handle) explicit

Constructor.

Magnum::Ui::AbstractLayer::AbstractLayer(AbstractLayer&&) noexcept

Move constructor.

Performs a destructive move, i.e. the original object isn't usable afterwards anymore.

LayerHandle Magnum::Ui::AbstractLayer::handle() const

Layer handle.

Returns the handle passed to the constructor.

LayerStates Magnum::Ui::AbstractLayer::state() const

Layer state.

See the LayerState enum for more information. By default no flags are set.

void Magnum::Ui::AbstractLayer::setNeedsUpdate(LayerStates state)

Mark the layer as needing an update.

Meant to be called by layer implementations when the data get modified. Expects that state is a non-empty subset of LayerState::NeedsDataUpdate, NeedsCommonDataUpdate, NeedsSharedDataUpdate, and if the layer advertises LayerFeature::Composite, also LayerState::NeedsCompositeOffsetSizeUpdate. See the flags for more information.

std::size_t Magnum::Ui::AbstractLayer::capacity() const

Current capacity of the data storage.

Can be at most 1048576. If create() is called and there's no free slots left, the internal storage gets grown.

std::size_t Magnum::Ui::AbstractLayer::usedCount() const

Count of used items in the data storage.

Always at most capacity(). Expired handles are counted among used as well. The operation is done with a complexity where is capacity().

bool Magnum::Ui::AbstractLayer::isHandleValid(LayerDataHandle handle) const

Whether a data handle is valid.

A handle is valid if it has been returned from create() before and remove() wasn't called on it yet. For LayerDataHandle::Null always returns false.

bool Magnum::Ui::AbstractLayer::isHandleValid(DataHandle handle) const

Whether a data handle is valid.

A shorthand for extracting a LayerHandle from handle using dataHandleLayer(), comparing it to handle() and if it's the same, calling isHandleValid(LayerDataHandle) const with a LayerDataHandle extracted from handle using dataHandleData(). See these functions for more information. For DataHandle::Null, LayerHandle::Null or LayerDataHandle::Null always returns false.

void Magnum::Ui::AbstractLayer::attach(DataHandle data, NodeHandle node)

Attach data to a node.

Makes the data handle tied to a particular node, meaning it gets included in draw or event processing depending on node position and visibility. Also, AbstractUserInterface::removeNode() called for node or any parent node will then mean that the data gets scheduled for removal during the next cleanNodes() call.

Expects that data is valid. The node can be anything including NodeHandle::Null, but if it's non-null and not valid the data will be scheduled for deletion during the next cleanNodes() call. If the data is already attached to some node, this will overwrite the previous attachment — i.e., it's not possible to have the same data attached to multiple nodes. The inverse, attaching multiple different data handles to a single node, is supported however.

If data wasn't attached to node before, calling this function causes LayerState::NeedsAttachmentUpdate to be set. Additionally, if node isn't NodeHandle::Null, LayerState::NeedsNodeOffsetSizeUpdate is set as well.

void Magnum::Ui::AbstractLayer::attach(LayerDataHandle data, NodeHandle node)

Attach data to a node assuming it belongs to this layer.

Like attach(DataHandle, NodeHandle) but without checking that data indeed belongs to this layer. See its documentation for more information.

NodeHandle Magnum::Ui::AbstractLayer::node(DataHandle data) const

Node attachment for given data.

Expects that data is valid. If given data isn't attached to any node, returns NodeHandle::Null. See also node(LayerDataHandle) const which is a simpler operation if the data is already known to belong to this layer.

The returned handle may be invalid if either the data got attached to an invalid node in the first place or the node or any of its parents were removed and AbstractUserInterface::clean() wasn't called since.

NodeHandle Magnum::Ui::AbstractLayer::node(LayerDataHandle data) const

Node attachment for given data assuming it belongs to this layer.

Like node(DataHandle) const but without checking that data indeed belongs to this layer. See its documentation for more information.

Containers::StridedArrayView1D<const NodeHandle> Magnum::Ui::AbstractLayer::nodes() const

Node attachments for all data.

Used internally from AbstractUserInterface::update(), meant to be also used by doUpdate() implementations to map data IDs to node handles. Size of the returned view is the same as capacity(). Items that are NodeHandle::Null are either data with no node attachments or corresponding to data that are freed.

Containers::StridedArrayView1D<const UnsignedShort> Magnum::Ui::AbstractLayer::generations() const

Generation counters for all data.

Meant to be used by code that only gets data IDs or masks but needs the full DataHandle / LayerDataHandle. Size of the returned view is the same as capacity().

void Magnum::Ui::AbstractLayer::setSize(const Vector2& size, const Vector2i& framebufferSize)

Set user interface size.

Used internally from AbstractUserInterface::setSize() and AbstractUserInterface::setLayerInstance(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Draw and that both sizes are non-zero. Delegates to doSetSize(), see its documentation for more information about the arguments.

void Magnum::Ui::AbstractLayer::cleanNodes(const Containers::StridedArrayView1D<const UnsignedShort>& nodeHandleGenerations)

Clean data attached to no longer valid nodes.

Used internally from AbstractUserInterface::clean(). Exposed just for testing purposes, there should be no need to call this function directly and doing so may cause internal AbstractUserInterface state update to misbehave. Assumes that nodeHandleGenerations contains handle generation counters for all nodes, where the index is implicitly the handle ID. They're used to decide about node attachment validity, data with invalid node attachments are then removed. Delegates to doClean(), see its documentation for more information about the arguments.

void Magnum::Ui::AbstractLayer::cleanData(const Containers::Iterable<AbstractAnimator>& animators)

Clean animations attached to no longer valid data.

Used internally from AbstractUserInterface::clean(). Exposed just for testing purposes, there should be no need to call this function directly and doing so may cause internal AbstractUserInterface state update to misbehave. Expects that all animators expose AnimatorFeature::DataAttachment and their AbstractAnimator::layer() matches handle(), and assumes that all such animators are passed together in a single call. Delegates to AbstractAnimator::cleanData() for every animator, see its documentation for more information.

Calling this function resets LayerState::NeedsDataClean, however note that behavior of this function is independent of state() — it performs the clean always regardless of what flags are set.

void Magnum::Ui::AbstractLayer::advanceAnimations(Nanoseconds time, Containers::MutableBitArrayView activeStorage, const Containers::StridedArrayView1D<Float>& factorStorage, Containers::MutableBitArrayView removeStorage, const Containers::Iterable<AbstractDataAnimator>& animators)

Advance data animations in animators assigned to this layer.

Used internally from AbstractUserInterface::advanceAnimations(). Exposed just for testing purposes, there should be no need to call this function directly and doing so may cause internal AbstractUserInterface state update to misbehave.

Expects that activeStorage, factorStorage and removeStorage have the same size, which is at least as large as the largest capacity of all animators, and that all animators expose AnimatorFeature::DataAttachment and their AbstractAnimator::layer() matches handle(), in other words that they were passed to assignAnimator(AbstractDataAnimator&) const earlier. Delegates to doAdvanceAnimations(Nanoseconds, Containers::MutableBitArrayView, const Containers::StridedArrayView1D<Float>&, Containers::MutableBitArrayView, const Containers::Iterable<AbstractDataAnimator>&), see its documentation for more information.

void Magnum::Ui::AbstractLayer::advanceAnimations(Nanoseconds time, Containers::MutableBitArrayView activeStorage, const Containers::StridedArrayView1D<Float>& factorStorage, Containers::MutableBitArrayView removeStorage, const Containers::Iterable<AbstractStyleAnimator>& animators)

Advance style animations in animators assigned to this layer.

Used internally from AbstractUserInterface::advanceAnimations(). Exposed just for testing purposes, there should be no need to call this function directly and doing so may cause internal AbstractUserInterface state update to misbehave.

Expects that activeStorage, factorStorage and removeStorage have the same size, which is at least as large as the largest capacity of all animators, and that all animators expose AnimatorFeature::DataAttachment and their AbstractAnimator::layer() matches handle(), in other words that they were passed to assignAnimator(AbstractStyleAnimator&) const earlier. Delegates to doAdvanceAnimations(Nanoseconds, Containers::MutableBitArrayView, const Containers::StridedArrayView1D<Float>&, Containers::MutableBitArrayView, const Containers::Iterable<AbstractStyleAnimator>&), see its documentation for more information.

void Magnum::Ui::AbstractLayer::update(LayerStates state, const Containers::StridedArrayView1D<const UnsignedInt>& dataIds, const Containers::StridedArrayView1D<const UnsignedInt>& clipRectIds, const Containers::StridedArrayView1D<const UnsignedInt>& clipRectDataCounts, const Containers::StridedArrayView1D<const Vector2>& nodeOffsets, const Containers::StridedArrayView1D<const Vector2>& nodeSizes, Containers::BitArrayView nodesEnabled, const Containers::StridedArrayView1D<const Vector2>& clipRectOffsets, const Containers::StridedArrayView1D<const Vector2>& clipRectSizes, const Containers::StridedArrayView1D<const Vector2>& compositeRectOffsets, const Containers::StridedArrayView1D<const Vector2>& compositeRectSizes)

Update visible layer data to given offsets and positions.

Used internally from AbstractUserInterface::update(). Exposed just for testing purposes, there should be no need to call this function directly and doing so may cause internal AbstractUserInterface state update to misbehave.

Expects that states isn't empty and is a subset of LayerState::NeedsNodeOffsetSizeUpdate, NeedsNodeOrderUpdate, NeedsNodeEnabledUpdate, NeedsDataUpdate, NeedsCommonDataUpdate, NeedsSharedDataUpdate and NeedsAttachmentUpdate, and NeedsCompositeOffsetSizeUpdate if the layer advertises LayerFeature::Composite, that the clipRectIds and clipRectDataCounts views have the same size, nodeOffsets and nodeSizes have the same size, clipRectOffsets and clipRectOffset have the same size and compositeRectOffsets and compositeRectSizes have the same size. If LayerFeature::Composite isn't supported, compositeRectOffsets and compositeRectSizes are expected to be empty. The nodeOffsets, nodeSizes and nodesEnabled views should be large enough to contain any valid node ID. If the layer advertises LayerFeature::Draw, expects that setSize() was called at least once before this function. Delegates to doUpdate(), see its documentation for more information about the arguments.

Calling this function resets LayerStates present in state, however note that behavior of this function is independent of state() — it performs the update only based on what's passed in state.

void Magnum::Ui::AbstractLayer::composite(AbstractRenderer& renderer, const Containers::StridedArrayView1D<const Vector2>& rectOffsets, const Containers::StridedArrayView1D<const Vector2>& rectSizes, std::size_t offset, std::size_t count)

Composite previously rendered contents.

Used internally from AbstractUserInterface::draw(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Composite, that the rectOffsets and rectSizes views have the same size and that offset and count fits into their size. Delegates to doComposite(), see its documentation for more information about the arguments.

void Magnum::Ui::AbstractLayer::draw(const Containers::StridedArrayView1D<const UnsignedInt>& dataIds, std::size_t offset, std::size_t count, const Containers::StridedArrayView1D<const UnsignedInt>& clipRectIds, const Containers::StridedArrayView1D<const UnsignedInt>& clipRectDataCounts, std::size_t clipRectOffset, std::size_t clipRectCount, const Containers::StridedArrayView1D<const Vector2>& nodeOffsets, const Containers::StridedArrayView1D<const Vector2>& nodeSizes, Containers::BitArrayView nodesEnabled, const Containers::StridedArrayView1D<const Vector2>& clipRectOffsets, const Containers::StridedArrayView1D<const Vector2>& clipRectSizes)

Draw a sub-range of visible layer data.

Used internally from AbstractUserInterface::draw(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Draw, offset and count fits into dataIds size, that the clipRectIds and clipRectDataCounts views have the same size, nodeOffsets and nodeSizes have the same size and clipRectOffsets and clipRectOffset have the same size. The nodeOffsets, nodeSizes and nodesEnabled views should be large enough to contain any valid node ID. Delegates to doDraw(), see its documentation for more information about the arguments.

void Magnum::Ui::AbstractLayer::pointerPressEvent(UnsignedInt dataId, PointerEvent& event)

Handle a pointer press event.

Used internally from AbstractUserInterface::pointerPressEvent(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Event and dataId is less than capacity(), with the assumption that the ID points to a valid data and PointerEvent::position() is relative to the node to which the data is attached. The event is expected to not be accepted yet. Delegates to doPointerPressEvent(), see its documentation for more information.

void Magnum::Ui::AbstractLayer::pointerReleaseEvent(UnsignedInt dataId, PointerEvent& event)

Handle a pointer release event.

Used internally from AbstractUserInterface::pointerReleaseEvent(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Event and dataId is less than capacity(), with the assumption that the ID points to a valid data and PointerEvent::position() is relative to the node to which the data is attached. The event is expected to not be accepted yet. Delegates to doPointerReleaseEvent(), see its documentation for more information.

void Magnum::Ui::AbstractLayer::pointerTapOrClickEvent(UnsignedInt dataId, PointerEvent& event)

Handle a pointer tap or click event.

Used internally from AbstractUserInterface::pointerReleaseEvent(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Event and dataId is less than capacity(), with the assumption that the ID points to a valid data and PointerEvent::position() is relative to the node to which the data is attached. The event is expected to be primary and to not be accepted yet. Delegates to doPointerTapOrClickEvent(), see its documentation for more information.

void Magnum::Ui::AbstractLayer::pointerMoveEvent(UnsignedInt dataId, PointerMoveEvent& event)

Handle a pointer move event.

Used internally from AbstractUserInterface::pointerMoveEvent(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Event and dataId is less than capacity(), with the assumption that the ID points to a valid data and PointerMoveEvent::position() is relative to the node to which the data is attached. The event is expected to not be accepted yet. Delegates to doPointerMoveEvent(), see its documentation for more information.

void Magnum::Ui::AbstractLayer::pointerEnterEvent(UnsignedInt dataId, PointerMoveEvent& event)

Handle a pointer enter event.

Used internally from AbstractUserInterface::pointerMoveEvent(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Event and dataId is less than capacity(), with the assumption that the ID points to a valid data and PointerMoveEvent::position() is relative to the node to which the data is attached, and PointerMoveEvent::relativePosition() is a zero vector, given that the event is meant to happen right after another event. The event is expected to be primary and to not be accepted yet. Delegates to doPointerEnterEvent(), see its documentation for more information.

void Magnum::Ui::AbstractLayer::pointerLeaveEvent(UnsignedInt dataId, PointerMoveEvent& event)

Handle a pointer leave event.

Used internally from AbstractUserInterface::pointerMoveEvent(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Event and dataId is less than capacity(), with the assumption that the ID points to a valid data and PointerMoveEvent::position() is relative to the node to which the data is attached, and PointerMoveEvent::relativePosition() is a zero vector, given that the event is meant to happen right after another event. The event is expected to be primary and to not be accepted yet. Delegates to doPointerLeaveEvent(), see its documentation for more information.

void Magnum::Ui::AbstractLayer::focusEvent(UnsignedInt dataId, FocusEvent& event)

Handle a focus event.

Used internally from AbstractUserInterface::focusEvent() and AbstractUserInterface::pointerPressEvent(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Event and dataId is less than capacity(), with the assumption that the ID points to a valid data. The event is expected to not be accepted yet. Delegates to doFocusEvent(), see its documentation for more information.

void Magnum::Ui::AbstractLayer::blurEvent(UnsignedInt dataId, FocusEvent& event)

Handle a blur event.

Used internally from AbstractUserInterface::focusEvent(), AbstractUserInterface::pointerPressEvent() and AbstractUserInterface::update(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Event and dataId is less than capacity(), with the assumption that the ID points to a valid data. The event is expected to not be accepted yet. Delegates to doBlurEvent(), see its documentation for more information.

void Magnum::Ui::AbstractLayer::keyPressEvent(UnsignedInt dataId, KeyEvent& event)

Handle a key press event.

Used internally from AbstractUserInterface::keyPressEvent(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Event and dataId is less than capacity(), with the assumption that the ID points to a valid data. The event is expected to not be accepted yet. Delegates to doKeyPressEvent(), see its documentation for more information.

void Magnum::Ui::AbstractLayer::keyReleaseEvent(UnsignedInt dataId, KeyEvent& event)

Handle a key release event.

Used internally from AbstractUserInterface::keyReleaseEvent(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Event and dataId is less than capacity(), with the assumption that the ID points to a valid data. The event is expected to not be accepted yet. Delegates to doKeyReleaseEvent(), see its documentation for more information.

void Magnum::Ui::AbstractLayer::textInputEvent(UnsignedInt dataId, TextInputEvent& event)

Handle a text input event.

Used internally from AbstractUserInterface::textInputEvent(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Event and dataId is less than capacity(), with the assumption that the ID points to a valid data. The event is expected to not be accepted yet. Delegates to doTextInputEvent(), see its documentation for more information.

void Magnum::Ui::AbstractLayer::visibilityLostEvent(UnsignedInt dataId, VisibilityLostEvent& event)

Handle a visibility lost event.

Used internally from AbstractUserInterface::update(). Exposed just for testing purposes, there should be no need to call this function directly. Expects that the layer supports LayerFeature::Event and dataId is less than capacity(), with the assumption that the ID points to a valid data. Delegates to doVisibilityLostEvent(), see its documentation for more information.

DataHandle Magnum::Ui::AbstractLayer::create(NodeHandle node = NodeHandle::Null) protected

Create a data.

Allocates a new handle in a free slot in the internal storage or grows the storage if there's no free slots left. Expects that there's at most 1048576 data. The returned handle can be removed again with remove(). If node is not NodeHandle::Null, directly attaches the created data to given node, equivalent to calling attach().

Calling this function causes LayerState::NeedsDataUpdate to be set. If node is not NodeHandle::Null, causes also LayerState::NeedsAttachmentUpdate and NeedsNodeOffsetSizeUpdate to be set. The subclass is meant to wrap this function in a public API and perform appropriate additional initialization work there.

void Magnum::Ui::AbstractLayer::remove(DataHandle handle) protected

Remove a data.

Expects that handle is valid. After this call, isHandleValid(DataHandle) const returns false for handle. See also remove(LayerDataHandle) which is a simpler operation if the data is already known to belong to this layer.

Calling this function causes LayerState::NeedsDataClean to be set. If handle is attached to a node, calling this function also causes LayerState::NeedsAttachmentUpdate to be set. Other than that, no flag is set to trigger a subsequent cleanNodes() or update() — instead the subclass is meant to wrap this function in a public API and perform appropriate cleanup work directly there.

void Magnum::Ui::AbstractLayer::remove(LayerDataHandle handle) protected

Remove a data assuming it belongs to this layer.

Expects that handle is valid. After this call, isHandleValid(LayerDataHandle) const returns false for handle. See also remove(DataHandle) which additionally checks that the data belongs to this layer.

Calling this function causes LayerState::NeedsDataClean to be set. If handle is attached to a node, calling this function also causes LayerState::NeedsAttachmentUpdate to be set. Other than that, no flag is set to trigger a subsequent cleanNodes() or update() — instead the subclass is meant to wrap this function in a public API and perform appropriate cleanup work directly there.

void Magnum::Ui::AbstractLayer::assignAnimator(AbstractDataAnimator& animator) const protected

Assign a data animator to this layer.

Expects that the layer supports LayerFeature::AnimateData, the animator supports AnimatorFeature::DataAttachment and that given animator wasn't passed to assignAnimator(AbstractDataAnimator&) const on any layer yet. On the other hand, it's possible to assign multiple different animators to the same layer. Saves handle() into AbstractAnimator::layer(), making it possible to call AbstractAnimator::create(Nanoseconds, Nanoseconds, DataHandle, UnsignedInt, AnimationFlags), AbstractAnimator::create(Nanoseconds, Nanoseconds, LayerDataHandle, UnsignedInt, AnimationFlags), AbstractAnimator::attach(AnimationHandle, DataHandle), AbstractAnimator::attach(AnimationHandle, LayerDataHandle), AbstractAnimator::attach(AnimatorDataHandle, DataHandle) and AbstractAnimator::attach(AnimatorDataHandle, LayerDataHandle) and pass the animator to advanceAnimations(Nanoseconds, Containers::MutableBitArrayView, const Containers::StridedArrayView1D<Float>&, Containers::MutableBitArrayView, const Containers::Iterable<AbstractDataAnimator>&).

A concrete layer implementation is meant to wrap this function in a public API, restricting to a more concrete animator type, in order to be able to safely cast back to that type in doAdvanceAnimations(Nanoseconds, Containers::MutableBitArrayView, const Containers::StridedArrayView1D<Float>&, Containers::MutableBitArrayView, const Containers::Iterable<AbstractDataAnimator>&).

See assignAnimator(AbstractStyleAnimator&) const for style animators, a corresponding API for an AbstractGenericAnimator is AbstractGenericAnimator::setLayer(), where the animator has the control over a concrete layer type instead.

void Magnum::Ui::AbstractLayer::assignAnimator(AbstractStyleAnimator& animator) const protected

Assign a style animator to this layer.

Expects that the layer supports LayerFeature::AnimateStyles, the animator supports AnimatorFeature::DataAttachment and that given animator wasn't passed to assignAnimator(AbstractStyleAnimator&) const on any layer yet. On the other hand, it's possible to assign multiple different animators to the same layer. Saves handle() into AbstractAnimator::layer(), making it possible to call AbstractAnimator::create(Nanoseconds, Nanoseconds, DataHandle, UnsignedInt, AnimationFlags), AbstractAnimator::create(Nanoseconds, Nanoseconds, LayerDataHandle, UnsignedInt, AnimationFlags), AbstractAnimator::attach(AnimationHandle, DataHandle), AbstractAnimator::attach(AnimationHandle, LayerDataHandle), AbstractAnimator::attach(AnimatorDataHandle, DataHandle) and AbstractAnimator::attach(AnimatorDataHandle, LayerDataHandle) and pass the animator to advanceAnimations(Nanoseconds, Containers::MutableBitArrayView, const Containers::StridedArrayView1D<Float>&, Containers::MutableBitArrayView, const Containers::Iterable<AbstractStyleAnimator>&).

A concrete layer implementation is meant to wrap this function in a public API, restricting to a more concrete animator type, in order to be able to safely cast back to that type in doAdvanceAnimations(Nanoseconds, Containers::MutableBitArrayView, const Containers::StridedArrayView1D<Float>&, Containers::MutableBitArrayView, const Containers::Iterable<AbstractStyleAnimator>&).

See assignAnimator(AbstractDataAnimator&) const for data animators, a corresponding API for an AbstractGenericAnimator is AbstractGenericAnimator::setLayer(), where the animator has the control over a concrete layer type instead.

LayerStates Magnum::Ui::AbstractLayer::doState() const virtual private

Query layer state.

Called by state() to retrieve additional state bits that might have changed without layer's direct involvement, such as data shared between multiple layers getting modified by another layer. The implementation is expected to return a subset of LayerState::NeedsDataUpdate, NeedsCommonDataUpdate and NeedsSharedDataUpdate, and if the layer advertises LayerFeature::Composite, also LayerState::NeedsCompositeOffsetSizeUpdate.

Default implementation returns an empty set.

void Magnum::Ui::AbstractLayer::doSetSize(const Vector2& size, const Vector2i& framebufferSize) virtual private

Set user interface size.

Implementation for setSize(), which is called from AbstractUserInterface::setSize() whenever the UI size or the framebuffer size changes, and from AbstractUserInterface::setLayerInstance() if the UI size is already set at the time the function is called. Called only if LayerFeature::Draw is supported. The implementation is expected to update its internal rendering state such as projection matrices and other framebuffer-related state. If any nodes are already created, the implementation can expect a followup doUpdate() call with up-to-date node positions and sizes.

Default implementation does nothing.

void Magnum::Ui::AbstractLayer::doClean(Containers::BitArrayView dataIdsToRemove) virtual private

Clean no longer valid layer data.

Implementation for cleanNodes(), which is called from AbstractUserInterface::clean() (and transitively from AbstractUserInterface::update()) whenever UserInterfaceState::NeedsNodeClean or any of the states that imply it are present in AbstractUserInterface::state().

The dataIdsToRemove view has the same size as capacity() and is guaranteed to have bits set only for valid data IDs, i.e. data IDs that are already removed are not set.

This function may get also called with dataIdsToRemove having all bits zero.

Default implementation does nothing.

void Magnum::Ui::AbstractLayer::doAdvanceAnimations(Nanoseconds time, Containers::MutableBitArrayView activeStorage, const Containers::StridedArrayView1D<Float>& factorStorage, Containers::MutableBitArrayView removeStorage, const Containers::Iterable<AbstractDataAnimator>& animators) virtual private

Advance data animations in animators assigned to this layer.

Implementation for advanceAnimations(), which is called from AbstractUserInterface::advanceAnimations() whenever UserInterfaceState::NeedsAnimationAdvance is present in AbstractUserInterface::state() and there are animators assigned to given layer.

The activeStorage, factorStorage and removeStorage are guaranteed to be at least as large as the largest capacity of all animators. The animators are all guaranteed to support AnimatorFeature::DataAttachment, with their AbstractAnimator::layer() matching handle(), in other words that they were passed to assignAnimator(AbstractDataAnimator&) const earlier.

For each animator in animators the implementation is expected to call AbstractAnimator::update() to fill a correctly-sized slice of activeStorage, factorStorage and removeStorage; then, if the returned value says advance is needed, pass the slices of activeStorage, factorStorage and removeStorage to the animator-specific advance function; and then, if the returned value says clean is needed, pass the slice of removeStorage to AbstractAnimator::clean().

Assuming the layer implementation publicizes assignAnimator(AbstractDataAnimator&) const with a restricted type, the animators can then be safely cast back to that type in order to call a concrete layer-specific advance function.

void Magnum::Ui::AbstractLayer::doAdvanceAnimations(Nanoseconds time, Containers::MutableBitArrayView activeStorage, const Containers::StridedArrayView1D<Float>& factorStorage, Containers::MutableBitArrayView removeStorage, const Containers::Iterable<AbstractStyleAnimator>& animators) virtual private

Advance style animations in animators assigned to this layer.

Implementation for advanceAnimations(), which is called from AbstractUserInterface::advanceAnimations() whenever UserInterfaceState::NeedsAnimationAdvance is present in AbstractUserInterface::state() and there are animators assigned to given layer.

The activeStorage, factorStorage and removeStorage are guaranteed to be at least as large as the largest capacity of all animators. The animators are all guaranteed to support AnimatorFeature::DataAttachment, with their AbstractAnimator::layer() matching handle(), in other words that they were passed to assignAnimator(AbstractStyleAnimator&) const earlier.

For each animator in animators the implementation is expected to call AbstractAnimator::update() to fill a correctly-sized slice of activeStorage, factorStorage and removeStorage; then, if the returned value says advance is needed, pass the slices of activeStorage, factorStorage and removeStorage to the animator-specific advance function; and then, if the returned value says clean is needed, pass the slice of removeStorage to AbstractAnimator::clean().

Assuming the layer implementation publicizes assignAnimator(AbstractStyleAnimator&) const with a restricted type, the animators can then be safely cast back to that type in order to call a concrete layer-specific advance function.

void Magnum::Ui::AbstractLayer::doUpdate(LayerStates state, const Containers::StridedArrayView1D<const UnsignedInt>& dataIds, const Containers::StridedArrayView1D<const UnsignedInt>& clipRectIds, const Containers::StridedArrayView1D<const UnsignedInt>& clipRectDataCounts, const Containers::StridedArrayView1D<const Vector2>& nodeOffsets, const Containers::StridedArrayView1D<const Vector2>& nodeSizes, Containers::BitArrayView nodesEnabled, const Containers::StridedArrayView1D<const Vector2>& clipRectOffsets, const Containers::StridedArrayView1D<const Vector2>& clipRectSizes, const Containers::StridedArrayView1D<const Vector2>& compositeRectOffsets, const Containers::StridedArrayView1D<const Vector2>& compositeRectSizes) virtual private

Update visible layer data to given offsets and positions.

Implementation for update(), which is called from AbstractUserInterface::update() whenever UserInterfaceState::NeedsDataUpdate or any of the global or layer-specific states that imply it are present in AbstractUserInterface::state(). Is always called after doClean() and before doComposite() and doDraw(), with at least one doSetSize() call happening at some point before.

The state is guaranteed to be a subset of LayerState::NeedsNodeOffsetSizeUpdate, NeedsNodeOrderUpdate, NeedsNodeEnabledUpdate, NeedsDataUpdate, NeedsCommonDataUpdate and NeedsSharedDataUpdate and the implementation can make use of this information to skip some of its internal update logic. It can however also update everything always. The LayerState::NeedsAttachmentUpdate flag isn't passed through from update() as it's only meant to be used by the layer to signalize a state update to AbstractUserInterface, not the other way around.

Node handles corresponding to dataIds are available in nodes(), node IDs can be then extracted from the handles using nodeHandleId(). The node IDs then index into the nodeOffsets, nodeSizes and nodesEnabled views. The nodeOffsets, nodeSizes and nodesEnabled have the same size and are guaranteed to be large enough to contain any valid node ID.

All nodes() at indices corresponding to dataIds are guaranteed to not be NodeHandle::Null at the time this function is called. The nodeOffsets, nodeSizes and nodesDisabled arrays may contain random or uninitialized values for nodes different than those referenced from dataIds, such as for nodes that are not currently visible or freed node handles.

The node data are meant to be clipped by rects defined in clipRectOffsets and clipRectSizes. The clipRectIds and clipRectDataCounts have the same size and specify which of these rects is used for which data. For example, a sequence of {3, 2}, {0, 4}, {1, 7} means clipping the first two data with clip rect 3, then the next four data with clip rect 0 and then the next seven data with clip rect 1. The sum of all clipRectDataCounts is equal to the size of the dataIds array. The clipRectOffsets and clipRectSizes have the same size and are guaranteed to be large enough to contain any ID from clipRectIds. They're in the same coordinate system as nodeOffsets and nodeSizes, a zero offset and a zero size denotes that no clipping is needed. Tt's up to the implementation whether it clips the actual data directly or whether it performs clipping at draw time.

The compositeRectOffsets and compositeRectOffsets have the same size and define rectangles to be used by compositing operations, i.e. intersections of node rectangles with corresponding clip rectangles. If the layer doesn't advertise LayerFeature::Composite, the views are empty.

This function may get also called with dataIds being empty, for example when setNeedsUpdate() was called but the layer doesn't have any data currently visible.

Default implementation does nothing. Data passed to this function are subsequently passed to doComposite() / doDraw() calls as well, the only difference is that doUpdate() gets called just once with all data to update, while doComposite() / doDraw() is called several times with different sub-ranges of the data based on desired draw order.

void Magnum::Ui::AbstractLayer::doComposite(AbstractRenderer& renderer, const Containers::StridedArrayView1D<const Vector2>& compositeRectOffsets, const Containers::StridedArrayView1D<const Vector2>& compositeRectSizes, std::size_t offset, std::size_t count) virtual private

Composite previously rendered contents.

Implementation for composite(), which is called from AbstractUserInterface::draw(). Called only if LayerFeature::Composite is supported, it's guaranteed that doUpdate() was called at some point before this function with the exact same views passed to compositeRectOffsets and compositeRectSizes, see its documentation for their relations and constraints. This function is called after drawing contents of all layers earlier in the top-level node and layer draw order. It's guaranteed that doDraw() will get called after this function.

This function usually gets called several times with the same views but different offset and count. The range of compositeRectOffsets and compositeRectSizes views defined by offset and count contains rectangles that correspond to the layer data and can be used to restrict the compositing operation to only the area that's actually subsequently drawn.)

void Magnum::Ui::AbstractLayer::doDraw(const Containers::StridedArrayView1D<const UnsignedInt>& dataIds, std::size_t offset, std::size_t count, const Containers::StridedArrayView1D<const UnsignedInt>& clipRectIds, const Containers::StridedArrayView1D<const UnsignedInt>& clipRectDataCounts, std::size_t clipRectOffset, std::size_t clipRectCount, const Containers::StridedArrayView1D<const Vector2>& nodeOffsets, const Containers::StridedArrayView1D<const Vector2>& nodeSizes, Containers::BitArrayView nodesEnabled, const Containers::StridedArrayView1D<const Vector2>& clipRectOffsets, const Containers::StridedArrayView1D<const Vector2>& clipRectSizes) virtual private

Draw a sub-range of visible layer data.

Implementation for draw(), which is called from AbstractUserInterface::draw(). Called only if LayerFeature::Draw is supported, it's guaranteed that doUpdate() was called at some point before this function with the exact same views passed to dataIds, clipRectIds, clipRectDataCounts, nodeOffsets, nodeSizes, nodesEnabled, clipRectOffsets and clipRectSizes, see its documentation for their relations and constraints. If LayerFeature::Composite is supported as well, it's guaranteed that doComposite() was called before this function and at some point after doUpdate(), and after drawing contents of all layers earlier in the top-level node and layer draw order.

Like with doUpdate(), the clipRectOffsets and clipRectSizes are in the same coordinate system as nodeOffsets and nodeSizes. If performing the clipping at draw time (instead of clipping the actual data directly in doDraw()), the implementation may need to scale these to match actual framebuffer pixels, i.e. by multiplying them with Vector2{framebufferSize}/size inside doSetSize().

This function usually gets called several times with the same views but different offset, count, clipRectOffset and clipRectCount values in order to interleave the draws for a correct back-to-front order. In each call, the sum of all clipRectDataCounts in the range given by clipRectOffset and clipRectCount is equal to count. Unlike doUpdate() or doClean(), this function is never called with an empty count.

void Magnum::Ui::AbstractLayer::doPointerPressEvent(UnsignedInt dataId, PointerEvent& event) virtual private

Handle a pointer press event.

Implementation for pointerPressEvent(), which is called from AbstractUserInterface::pointerPressEvent(). See its documentation for more information about pointer event behavior, especially event capture. It's guaranteed that doUpdate() was called before this function with up-to-date data for dataId.

If the implementation handles the event, it's expected to call PointerEvent::setAccepted() on it to prevent it from being propagated further. If the event is primary, pointer capture is implicitly performed on a node that accepts this event. Call PointerEvent::setCaptured() to disable it or to adjust the behavior in case of a non-primary event.

Default implementation does nothing, i.e. the event gets implicitly propagated further.

void Magnum::Ui::AbstractLayer::doPointerReleaseEvent(UnsignedInt dataId, PointerEvent& event) virtual private

Handle a pointer release event.

Implementation for pointerReleaseEvent(), which is called from AbstractUserInterface::pointerReleaseEvent(). See its documentation for more information about pointer event behavior, especially event capture. It's guaranteed that doUpdate() was called before this function with up-to-date data for dataId.

If the implementation handles the event, it's expected to call PointerEvent::setAccepted() on it to prevent it from being propagated further. If the event is primary, pointer capture is implicitly released after, thus calling PointerEvent::setCaptured() only has an effect for non-primary events.

Default implementation does nothing, i.e. the event gets implicitly propagated further.

void Magnum::Ui::AbstractLayer::doPointerTapOrClickEvent(UnsignedInt dataId, PointerEvent& event) virtual private

Handle a pointer tap or click event.

Implementation for pointerTapOrClickEvent(), which is called from AbstractUserInterface::pointerReleaseEvent(). See its documentation for more information about pointer event behavior, especially event capture. It's guaranteed that doUpdate() was called before this function with up-to-date data for dataId, the event is guaranteed to be always primary.

Unlike doPointerReleaseEvent(), the accept status is ignored for this event, as the event isn't propagated anywhere if it's not handled. Thus calling PointerEvent::setAccepted() has no effect here. Pointer capture is also implicitly released after this event, thus calling PointerEvent::setCaptured() has no effect either.

Default implementation does nothing.

void Magnum::Ui::AbstractLayer::doPointerMoveEvent(UnsignedInt dataId, PointerMoveEvent& event) virtual private

Handle a pointer move event.

Implementation for pointerMoveEvent(), which is called from AbstractUserInterface::pointerMoveEvent(). See its documentation for more information about pointer event behavior, especially event capture, hover and relation to doPointerEnterEvent() and doPointerLeaveEvent(). It's guaranteed that doUpdate() was called before this function with up-to-date data for dataId.

If the implementation handles the event, it's expected to call PointerEvent::setAccepted() on it to prevent it from being propagated further. Pointer capture behavior for remaining pointer events can be changed using PointerMoveEvent::setCaptured().

Default implementation does nothing, i.e. the event gets implicitly propagated further. That also implies the node is never marked as hovered for primary events and enter / leave events are not emitted for it.

void Magnum::Ui::AbstractLayer::doPointerEnterEvent(UnsignedInt dataId, PointerMoveEvent& event) virtual private

Handle a pointer enter event.

Implementation for pointerEnterEvent(), which is called from AbstractUserInterface::pointerMoveEvent() if the currently hovered node changed to one containing dataId. See its documentation for more information about relation of pointer enter/leave events to doPointerMoveEvent(). It's guaranteed that doUpdate() was called before this function with up-to-date data for dataId, the event is guaranteed to be always primary.

Unlike doPointerMoveEvent(), the accept status is ignored for enter and leave events, as the event isn't propagated anywhere if it's not handled. Thus calling PointerEvent::setAccepted() has no effect here. On the other hand, pointer capture behavior for remaining pointer events can be changed using PointerMoveEvent::setCaptured() here as well.

Default implementation does nothing.

void Magnum::Ui::AbstractLayer::doPointerLeaveEvent(UnsignedInt dataId, PointerMoveEvent& event) virtual private

Handle a pointer leave event.

Implementation for pointerEnterEvent(), which is called from AbstractUserInterface::pointerMoveEvent() if the currently hovered node changed away from one containing dataId. See its documentation for more information about relation of pointer enter/leave events to doPointerMoveEvent(). It's guaranteed that doUpdate() was called before this function with up-to-date data for dataId, the event is guaranteed to be always primary.

Unlike doPointerMoveEvent(), the accept status is ignored for enter and leave events, as the event isn't propagated anywhere if it's not handled. Thus calling PointerEvent::setAccepted() has no effect here. On the other hand, pointer capture behavior for remaining pointer events can be changed using PointerMoveEvent::setCaptured() here as well.

Default implementation does nothing.

void Magnum::Ui::AbstractLayer::doFocusEvent(UnsignedInt dataId, FocusEvent& event) virtual private

Handle a focus event.

Implementation for focusEvent(), which is called from AbstractUserInterface::focusEvent() and AbstractUserInterface::pointerPressEvent(). See their documentation for more information about focus and blur event behavior. It's guaranteed that doUpdate() was called before this function with up-to-date data for dataId.

If the implementation handles the event, it's expected to call FocusEvent::setAccepted() on it to cause the node to be marked as focused. If it doesn't, the node doesn't get marked as focused and depending on what AbstractUserInterface API the event originated in, the previously focused node stays or gets blurred.

Default implementation does nothing.

void Magnum::Ui::AbstractLayer::doBlurEvent(UnsignedInt dataId, FocusEvent& event) virtual private

Handle a blur event.

Implementation for blurEvent(), which is called from AbstractUserInterface::focusEvent() and AbstractUserInterface::pointerPressEvent(). See their documentation for more information about focus and blur event behavior. It's guaranteed that doUpdate() was called before this function with up-to-date data for dataId.

Unlike doFocusEvent(), the accept status is ignored for blur events, as the node is still unmarked as focused if the event is not handled. Thus calling FocusEvent::setAccepted() has no effect here.

Default implementation does nothing.

void Magnum::Ui::AbstractLayer::doKeyPressEvent(UnsignedInt dataId, KeyEvent& event) virtual private

Handle a key press event.

Implementation for keyPressEvent(), which is called from AbstractUserInterface::keyPressEvent(). See its documentation for more information about key event behavior. It's guaranteed that doUpdate() was called before this function with up-to-date data for dataId.

If the implementation handles the event, it's expected to call KeyEvent::setAccepted() on it to prevent it from being propagated further.

Default implementation does nothing, i.e. the event gets implicitly propagated further.

void Magnum::Ui::AbstractLayer::doKeyReleaseEvent(UnsignedInt dataId, KeyEvent& event) virtual private

Handle a pointer release event.

Implementation for keyReleaseEvent(), which is called from AbstractUserInterface::keyReleaseEvent(). See its documentation for more information. It's guaranteed that doUpdate() was called before this function with up-to-date data for dataId.

If the implementation handles the event, it's expected to call KeyEvent::setAccepted() on it to prevent it from being propagated further.

Default implementation does nothing, i.e. the event gets implicitly propagated further.

void Magnum::Ui::AbstractLayer::doTextInputEvent(UnsignedInt dataId, TextInputEvent& event) virtual private

Handle a text input event.

Implementation for textInputEvent(), which is called from AbstractUserInterface::textInputEvent(). See its documentation for more information about text input event behavior. It's guaranteed that doUpdate() was called before this function with up-to-date data for dataId.

If the implementation handles the event, it's expected to call TextInputEvent::setAccepted() on it to prevent it from being propagated further.

Default implementation does nothing, i.e. the event gets implicitly propagated further.

void Magnum::Ui::AbstractLayer::doVisibilityLostEvent(UnsignedInt dataId, VisibilityLostEvent& event) virtual private

Handle a visibility lost event.

Implementation for visibilityLostEvent(), which is called from AbstractUserInterface::update() if the currently hovered, pressed, captured or focused node containing dataId can no longer receive events due to NodeFlag::Hidden, NodeFlag::NoEvents or NodeFlag::Disabled being set on the node or any of its parents, or if a currently focused node is no longer NodeFlag::Focusable.

Default implementation does nothing.