Class PivotedRenderables

Namespace

AlphaFramework.Presentation

Assembly

AlphaFramework.Presentation.dll

An ICollection<T> facade over the root renderables of a Scene that groups everything belonging to one owner under a shared transform.

public sealed class PivotedRenderables : ICollection<PositionableRenderable>, IEnumerable<PositionableRenderable>, IEnumerable

Inheritance

object

PivotedRenderables

Implements

ICollection<PositionableRenderable>

IEnumerable<PositionableRenderable>

IEnumerable

Remarks

ModelViewSync<TModel, TView> knows nothing about render hierarchies; it only adds and removes flat representations. Create callbacks therefore call AddTo<T>(T, object, string?) to put a renderable into an owner's group. The subsequent Add(PositionableRenderable) then leaves it where it is, while Remove(PositionableRenderable) works for either case.

A group only gets a Pivot of its own once more than one thing needs to share the owner's transform. While a group holds a single renderable, that renderable carries the transform itself and its own local transform is folded into PreTransform. Adding a second renderable or attaching a light or sound promotes the group to a pivot, which takes over the owner's position, rotation and scale; it is never demoted again.

Renderables added to a group remain owned by the caller: releasing a group only disposes the Pivot itself.

Constructors

PivotedRenderables(ICollection<PositionableRenderable>)

An ICollection<T> facade over the root renderables of a Scene that groups everything belonging to one owner under a shared transform.

public PivotedRenderables(ICollection<PositionableRenderable> roots)

Parameters

roots ICollection<PositionableRenderable>

The scene's root renderables, usually Positionables.

Remarks

ModelViewSync<TModel, TView> knows nothing about render hierarchies; it only adds and removes flat representations. Create callbacks therefore call AddTo<T>(T, object, string?) to put a renderable into an owner's group. The subsequent Add(PositionableRenderable) then leaves it where it is, while Remove(PositionableRenderable) works for either case.

A group only gets a Pivot of its own once more than one thing needs to share the owner's transform. While a group holds a single renderable, that renderable carries the transform itself and its own local transform is folded into PreTransform. Adding a second renderable or attaching a light or sound promotes the group to a pivot, which takes over the owner's position, rotation and scale; it is never demoted again.

Renderables added to a group remain owned by the caller: releasing a group only disposes the Pivot itself.

Properties

Count

Gets the number of elements contained in the ICollection<T>.

public int Count { get; }

Property Value

int

The number of elements contained in the ICollection<T>.

GroupedRenderables

All renderables that belong to some owner's group.

public IEnumerable<PositionableRenderable> GroupedRenderables { get; }

Property Value

IEnumerable<PositionableRenderable>

Remarks

Excludes the Pivots themselves, which have no geometry.

IsReadOnly

Gets a value indicating whether the ICollection<T> is read-only.

public bool IsReadOnly { get; }

Property Value

bool

true if the ICollection<T> is read-only; otherwise, false.

Methods

Add(PositionableRenderable)

Adds an item to the ICollection<T>.

public void Add(PositionableRenderable item)

Parameters

item PositionableRenderable

The object to add to the ICollection<T>.

Exceptions

NotSupportedException

The ICollection<T> is read-only.

AddTo<T>(T, object, string?)

Adds a renderable to an owner's group, so that it follows the owner's transform.

public T AddTo<T>(T renderable, object owner, string? name = null) where T : PositionableRenderable

Parameters

renderable T

The renderable, with its placement relative to the owner already applied to Position and friends.

owner object

An object identifying the group, usually an element of the game world.

name string

The Name to give a Pivot created for this group.

Returns

T

renderable, so that this can be used inline in create callbacks.

Type Parameters

T

AnchorFor(object)

The node that carries an owner's transform; null if nothing belongs to that owner.

public PositionableRenderable? AnchorFor(object owner)

Parameters

owner object

Returns

PositionableRenderable

Remarks

This is either the group's Pivot or, for a group holding a single renderable, that renderable.

Clear()

Removes all items from the ICollection<T>.

public void Clear()

Exceptions

NotSupportedException

The ICollection<T> is read-only.

Contains(PositionableRenderable)

Determines whether the ICollection<T> contains a specific value.

public bool Contains(PositionableRenderable item)

Parameters

item PositionableRenderable

The object to locate in the ICollection<T>.

Returns

bool

true if item is found in the ICollection<T>; otherwise, false.

CopyTo(PositionableRenderable[], int)

Copies the elements of the ICollection<T> to an Array, starting at a particular Array index.

public void CopyTo(PositionableRenderable[] array, int arrayIndex)

Parameters

array PositionableRenderable[]

The one-dimensional Array that is the destination of the elements copied from ICollection<T>. The Array must have zero-based indexing.

arrayIndex int

The zero-based index in array at which copying begins.

Exceptions

ArgumentNullException

array is null.

ArgumentOutOfRangeException

arrayIndex is less than 0.

ArgumentException

The number of elements in the source ICollection<T> is greater than the available space from arrayIndex to the end of the destination array.

GetEnumerator()

Returns an enumerator that iterates through the collection.

public IEnumerator<PositionableRenderable> GetEnumerator()

Returns

IEnumerator<PositionableRenderable>

An enumerator that can be used to iterate through the collection.

Remarks

The scene roots already cover collapsed members and pivots, so only what lives below them is added.

LocalTransformOf(PositionableRenderable)

The transform that places a grouped renderable's geometry in its owner's coordinate system.

public Matrix LocalTransformOf(PositionableRenderable renderable)

Parameters

renderable PositionableRenderable

Returns

Matrix

Remarks

Reading Position directly is not enough, because a collapsed member uses it for the owner's world position.

MovePlacements(PositionableRenderable, PositionableRenderable)

Moves all renderables currently placed underneath from over to to.

public void MovePlacements(PositionableRenderable from, PositionableRenderable to)

Parameters

from PositionableRenderable

to PositionableRenderable

Remarks

Use this when a parent renderable is replaced by a freshly built one.

PivotFor(object, string?)

Gets the Pivot of an owner's group, creating it if there is none yet.

public Pivot PivotFor(object owner, string? name = null)

Parameters

owner object

An object identifying the group, usually an element of the game world.

name string

The Name to give a newly created pivot.

Returns

Pivot

Remarks

Use this for objects that are not renderables themselves but resolve their position through one, i.e. lights and sounds. It permanently keeps the group on a pivot, because a collapsed member's transform carries its own geometry's placement, which must not leak into such attachments.

PlaceUnder<T>(T, PositionableRenderable)

Places a renderable in the local coordinate system of parent instead of at the scene root.

public T PlaceUnder<T>(T renderable, PositionableRenderable parent) where T : PositionableRenderable

Parameters

renderable T

parent PositionableRenderable

Returns

T

renderable, so that this can be used inline in create callbacks.

Type Parameters

T

Remarks

Unlike AddTo<T>(T, object, string?) this names the parent directly, for hierarchies that are not built around an owner.

Release(object)

Drops an owner's group, disposing a Pivot it may have created.

public void Release(object owner)

Parameters

owner object

Remarks

Groups that hold no renderables are dropped automatically; this is only needed for ones kept alive by PivotFor(object, string?).

ReleaseAll()

Drops all groups, disposing the Pivots they created.

public void ReleaseAll()

Remove(PositionableRenderable)

Removes the first occurrence of a specific object from the ICollection<T>.

public bool Remove(PositionableRenderable item)

Parameters

item PositionableRenderable

The object to remove from the ICollection<T>.

Returns

bool

true if item was successfully removed from the ICollection<T>; otherwise, false. This method also returns false if item is not found in the original ICollection<T>.

Exceptions

NotSupportedException

The ICollection<T> is read-only.