Photon Quantum 2.1.1

Classes | Public Member Functions | Properties | List of all members
Quantum.PhysicsJoints2D Struct Reference

A component holding one or more Physics2D.Joint, defining connections between a 2D Physics Body and anchors according to velocity and/or position constraints. More...

Inherits Quantum.IComponent.

Classes

struct  JointsIterator
 An auxiliary struct to iterate over the joints on a PhysicsJoints2D component. Use PhysicsJoints2D.GetIterator to acquire an iterator for the component's joint buffer. More...
 

Public Member Functions

void AddJoint (FrameBase f, ref Joint joint)
 Adds a Physics2D.Joint to the component. If the buffer is at full Capacity, a new buffer will be allocated with double the capacity and existing entries are copied over. In that case, the previous buffer is not disposed immediately and cached pointers are still valid, although outdated. More...
 
JointsIterator GetIterator (FrameBase f, bool reverseOrder=true)
 Gets an auxiliary struct to iterate over the joints in this component. See also TryGetJoints and GetJoints to have direct access to the buffer. More...
 
JointGetJoints (FrameBase f, out Int32 count)
 Gets the currently allocated buffer for the component joints. See also GetIterator to iterate over the buffer with an auxiliary structure. More...
 
void RemoveAt (FrameBase f, int index)
 Removes the joint at the specified index of the component's joints buffer, while keeping the order of the remaining objects. If the remaining elements do not need to be kept in order, RemoveAtUnordered is a cheaper option. More...
 
void RemoveAtUnordered (FrameBase f, int index)
 Removes the joint at the specified index of the component's joints buffer. The order of the elements with indices greater than index is not kept. If the order must be kept, use RemoveAt instead. More...
 
bool RemoveJoints (FrameBase f, int? userTag=null)
 Removes all joints in the component that have a Physics2D.Joint.UserTag field matching the specified userTag . If none is specified, all joints are removed. More...
 
bool TryGetJoints (FrameBase f, out Joint *joints, out Int32 count)
 Gets the currently allocated buffer for the component joints, if it has one. See also GetIterator to iterate over the buffer with an auxiliary structure. More...
 

Properties

UInt16 Capacity [get]
 The number of joints the currently allocated buffer can hold before having to be resized. More...
 
UInt16 Count [get]
 The current amount of joints tracked by the component. More...
 

Detailed Description

A component holding one or more Physics2D.Joint, defining connections between a 2D Physics Body and anchors according to velocity and/or position constraints.

Member Function Documentation

◆ AddJoint()

void Quantum.PhysicsJoints2D.AddJoint ( FrameBase  f,
ref Joint  joint 
)
inline

Adds a Physics2D.Joint to the component. If the buffer is at full Capacity, a new buffer will be allocated with double the capacity and existing entries are copied over. In that case, the previous buffer is not disposed immediately and cached pointers are still valid, although outdated.

Parameters
fThe current frame.
jointThe joint that will be added to the component.

◆ RemoveJoints()

bool Quantum.PhysicsJoints2D.RemoveJoints ( FrameBase  f,
int?  userTag = null 
)
inline

Removes all joints in the component that have a Physics2D.Joint.UserTag field matching the specified userTag . If none is specified, all joints are removed.

This method does not keep the order of remaining elements in the buffer. To achieve that instead, use GetJoints and RemoveAt while iterating the buffer in reverse order.

Parameters
fThe current frame.
userTagA numerical tag that can be used to identify a joint or a group of joints. Any joint in the component that matches the tag will be removed. If none is specified, all joints are removed.
Returns
True if at least one joint has been removed.
const int removeJointsUserTag = 42;
var jointsComponent = f.Unsafe.GetPointer<PhysicsJoints2D>(entity);
if (removeAll) {
jointsComponent->RemoveJoints(f);
} else {
jointsComponent->RemoveJoints(f, removeJointsUserTag);
}

◆ RemoveAt()

void Quantum.PhysicsJoints2D.RemoveAt ( FrameBase  f,
int  index 
)
inline

Removes the joint at the specified index of the component's joints buffer, while keeping the order of the remaining objects. If the remaining elements do not need to be kept in order, RemoveAtUnordered is a cheaper option.

Parameters
fThe current frame.
indexThe index of the element to be removed.
Exceptions
NullReferenceExceptionIf the joints buffer is not allocated.
ArgumentOutOfRangeExceptionIf the index is outside the valid range.
var jointsComponent = f.Unsafe.GetPointer<PhysicsJoints2D>(entity);
if (jointsComponent->TryGetJoints(f, out var joints, out var count)) {
// by iterating the buffer in reverse order we avoid skipping elements if also removing
for (var i = count - 1; i >= 0; i&ndash;) {
var current = joints + i;
if (current->Type == Physics2D.JointType.DistanceJoint) {
// removes the element at the current index, keeping the order of the remaining ones
jointsComponent->RemoveAt(f, i);
}
}
}

◆ RemoveAtUnordered()

void Quantum.PhysicsJoints2D.RemoveAtUnordered ( FrameBase  f,
int  index 
)
inline

Removes the joint at the specified index of the component's joints buffer. The order of the elements with indices greater than index is not kept. If the order must be kept, use RemoveAt instead.

Parameters
fThe current frame.
indexThe index of the element to be removed.
Exceptions
NullReferenceExceptionIf the joints buffer is not allocated.
ArgumentOutOfRangeExceptionIf the index is outside the valid range.
var jointsComponent = f.Unsafe.GetPointer<PhysicsJoints2D>(entity);
if (jointsComponent->TryGetJoints(f, out var joints, out var count)) {
// by iterating the buffer in reverse order we avoid skipping elements if also removing
for (var i = count - 1; i >= 0; i&ndash;) {
var current = joints + i;
if (current->Type == Physics2D.JointType.DistanceJoint) {
// removes the element at the current index
// the order of the elements with index greater than i is not ensured
jointsComponent->RemoveAtUnordered(f, i);
}
}
}

◆ TryGetJoints()

bool Quantum.PhysicsJoints2D.TryGetJoints ( FrameBase  f,
out Joint joints,
out Int32  count 
)
inline

Gets the currently allocated buffer for the component joints, if it has one. See also GetIterator to iterate over the buffer with an auxiliary structure.

Parameters
fThe current frame.
jointsThe allocated buffer for the component joints. Null if the buffer is not allocated.
countThe number of elements used in the buffer at the moment this method is called. 0 if the buffer is not allocated.
Returns
True if the buffer is allocated.
var jointsComponent = f.Unsafe.GetPointer<PhysicsJoints2D>(entity);
if (jointsComponent->TryGetJoints(f, out var joints, out var count)) {
for (var i = 0; i < count; i++) {
var current = joints + i;
Log.Info($"Joint Type {i}: {current->Type}");
}
}

◆ GetJoints()

Joint* Quantum.PhysicsJoints2D.GetJoints ( FrameBase  f,
out Int32  count 
)
inline

Gets the currently allocated buffer for the component joints. See also GetIterator to iterate over the buffer with an auxiliary structure.

Parameters
fThe current frame.
countThe number of elements used in the buffer at the moment this method is called.
Returns
The allocated buffer for the component joints.
Exceptions
NullReferenceExceptionIf the buffer is not allocated.
var jointsComponent = f.Unsafe.GetPointer<PhysicsJoints2D>(entity);
var joints = jointsComponent->GetJoints(f, out var count);
for (var i = 0; i < count; i++) {
var current = joints + i;
Log.Info($"Joint Type {i}: {current->Type}");
}

◆ GetIterator()

JointsIterator Quantum.PhysicsJoints2D.GetIterator ( FrameBase  f,
bool  reverseOrder = true 
)
inline

Gets an auxiliary struct to iterate over the joints in this component. See also TryGetJoints and GetJoints to have direct access to the buffer.

If new elements are added while iterating and this causes the buffer to be expanded, the iterator will keep iterating over the previous buffer, which is not immediately disposed (see AddJoint). In this case, further changes to elements in the buffer being iterated will not modify the elements on the new buffer. Hence, the addition of elements while iterating is not recommended, unless the access to the elements are read-only.

Parameters
fThe current frame.
reverseOrderIf the buffer elements should be iterated in reverse order. If true, allows the removal of elements while iterating without it causing some elements to be skipped.
Returns
A JointsIterator for the buffer of joints in this component.
var jointsComponent = f.Unsafe.GetPointer<PhysicsJoints2D>(entity);
var jointsIterator = jointsComponent->GetIterator(f);
while (jointsIterator.MoveNext()) {
// CurrentUnsafe is a pointer to the element in the buffer
jointsIterator.CurrentUnsafe->Enabled = true;
// Current is a copy of the joint being currently iterated
var jointCopy = jointsIterator.Current;
Assert.Check(jointCopy.Enabled);
// by default, the iterator will go through the elements in reverse order.
// this allows the removal of elements while iterating without this causing elements to be skipped as a byproduct.
if (jointCopy.Type == Physics2D.JointType.None) {
jointsComponent->RemoveAtUnordered(f, jointsIterator.CurrentIndex);
}
}

Property Documentation

◆ Count

UInt16 Quantum.PhysicsJoints2D.Count
get

The current amount of joints tracked by the component.

◆ Capacity

UInt16 Quantum.PhysicsJoints2D.Capacity
get

The number of joints the currently allocated buffer can hold before having to be resized.