Class LayerMasker

Allows convenient interpretation and creation of layer masks (bit-masks which indicate one or more layers) that can be used to interact with LayeredSpatialMap<T>.

Inheritance
Object
LayerMasker
Namespace: SadRogue.Primitives.SpatialMaps
Assembly: TheSadRogue.Primitives.dll
Syntax
public sealed class LayerMasker : Object
Remarks

A layer mask is simply a list of layers encoded as a bit mask. It is frequently used in LayeredSpatialMap<T> as an optional parameter that indicates what layers should apply to an operation or given set of functionality. LayeredSpatialMap defines its own LayerMask variable that should be used to retrieve layer masks for use with that object whenever possible. For layer masks needed outside of that, use Default; but this won't enforce the maximum number of layers automatically. There are also constants defined in LayerMasker to represent "all layers" and "no layers".

Constructors

LayerMasker(Int32)

Constructor. Takes the number of layers allowed, which must be more than 0 and less than or equal to 32.

Declaration
public LayerMasker(int numberOfLayers = 32)
Parameters
Type Name Description
Int32 numberOfLayers

The number of layers supported by this layer mask generator.

Fields

AllLayers

Layer-mask representing all layers.

Declaration
public readonly uint AllLayers
Field Value
Type Description
UInt32

Default

Default layer masker, that excludes no possible layers from its results.

Declaration
public static readonly LayerMasker Default
Field Value
Type Description
LayerMasker

NoLayers

Layer mask representing no layers.

Declaration
public readonly uint NoLayers
Field Value
Type Description
UInt32

Properties

NumberOfLayers

Maximum number of layers supported by this layer masker. Functions using layer masks enforce this limit, and will not consider layers outside the range [0, NumberOfLayers - 1]

Declaration
public int NumberOfLayers { get; }
Property Value
Type Description
Int32

Methods

AddLayers(UInt32, IEnumerable<Int32>)

Adds the given layers to the given layer mask, provided those layers are within the supported number of layers. Any layer outside of this range will not be added.

Declaration
public uint AddLayers(uint mask, IEnumerable<int> layers)
Parameters
Type Name Description
UInt32 mask

The mask to add the layers to.
IEnumerable<Int32> layers

Layers to include in the resulting layer mask.
Returns
Type Description
UInt32

A layer mask including any original layers that were in the given mask (regardless of whether they were within the supported number of layers), as well as the new layers provided (provided they are within the supported number of layers).

AddLayers(UInt32, Int32[])

Adds the given layers to the given layer mask, provided those layers are within the supported number of layers. Any layer outside of this range in either of the function's parameters will not be included.

Declaration
public uint AddLayers(uint mask, params int[] layers)
Parameters
Type Name Description
UInt32 mask

The mask to add the layers to.
Int32[] layers

Layers to include in the resulting layer mask.
Returns
Type Description
UInt32

A layer mask including any original layers that were in the given mask, as well as the new layers provided. However, the mask will exclude any layers not within the range of this LayerMasker's supported layers.

AddLayers(UInt32, UInt32)

Adds layers active in the mask addMask to the mask value, and returns the result. The result will include all layers on in the original mask, as well as all layers on in addMask, provided those layers are within the supported number of layers. Any layer outside of this range will not be added.

Declaration
public uint AddLayers(uint mask, uint addMask)
Parameters
Type Name Description
UInt32 mask
UInt32 addMask
Returns
Type Description
UInt32

HasLayer(UInt32, Int32)

Returns whether or not a layer is contained within the given layer mask. Returns false if the layer given is outside the supported number of layers.

Declaration
public bool HasLayer(uint mask, int layer)
Parameters
Type Name Description
UInt32 mask

Layer mask to check.
Int32 layer

Layer to check for.
Returns
Type Description
Boolean

True if the given layer is present in the given layer mask, false if it is not or the layer is outside the supported number of layers for this LayerMasker.

Layers(UInt32)

Returns a custom enumerator that will enumerate all layers contained within the given layer mask (that fall within the supported number of layers). This function is intended to be used primarily with a foreach loop (see remarks).

Declaration
public LayerMaskEnumerator Layers(uint mask)
Parameters
Type Name Description
UInt32 mask

Layer mask to return layers for.
Returns
Type Description
LayerMaskEnumerator

All layers contained within the given layer mask that fall within the supported number of layers for this LayerMasker.
Remarks

This function returns a custom value type which can be treated like an enumerator and used with C#'s foreach loop. It is intended to be used like so:

foreach (int layerID in myLayerMasker.Layers(myLayerMask))
    Console.WriteLine($"Do something with layer {layerID}.")

This custom iterator will perform many times better (up to 25x better, in fact) than an IEnumerable, when used in a foreach loop, since it is a value type and thus incurs no GC allocation and no boxing/unboxing.

The returned enumerator also contains a function you can use to retrieve an IEnumerable if you wish to use the returned values with System.Linq or similar:

var array = myLayerMasker.Layers(myLayerMask).ToEnumerable().ToArray()

Note, however, that using this function will entirely erase the performance benefits of the custom type.

Mask(IEnumerable<Int32>)

Gets a layer mask including exactly the given layer indices. Any layer given outside the maximum number of layers is ignored, and will not be added to the resulting mask.

Declaration
public uint Mask(IEnumerable<int> layers)
Parameters
Type Name Description
IEnumerable<Int32> layers

Layers to include in generated layer mask.
Returns
Type Description
UInt32

A layer mask including exactly those layers in the input that were within the supported number of layers.

Mask(Int32[])

Gets a layer mask including exactly the given layer indices. Any layer given outside the maximum number of layers is ignored, and will not be added to the resulting mask.

Declaration
public uint Mask(params int[] layers)
Parameters
Type Name Description
Int32[] layers

One or more layers to include in generated layer mask.
Returns
Type Description
UInt32

A layer mask including exactly those layers in the input that were within the supported number of layers.

MaskAllAbove(Int32)

Generates and returns a layer mask including the given layer and any layer above (greater than) it. Layers not in the supported number of layers will be ignored, and will not be added to the resulting layer mask.

Declaration
public uint MaskAllAbove(int layer)
Parameters
Type Name Description
Int32 layer

Layer to start the mask at.
Returns
Type Description
UInt32

A layer mask including the specified layer and all layers above it, provided those layers fall within the supported number of layers.

MaskAllBelow(Int32)

Generates and returns a layer mask including the given layer and any layer below (less than) it. Layers not in the supported number of layers will be ignored, and will not be added to the resulting layer mask.

Declaration
public uint MaskAllBelow(int layer)
Parameters
Type Name Description
Int32 layer

Layer to start the mask at.
Returns
Type Description
UInt32

A layer mask including the specified layer and all layers below it, provided those layers fall within the supported number of layers.

Extension Methods