Struct InputEventBuffer

A buffer of raw memory holding a sequence of InputEvent.

Inherited Members

Namespace: UnityEngine.InputSystem.LowLevel

Syntax

public struct InputEventBuffer : IEnumerable<InputEventPtr>, IEnumerable, IDisposable, ICloneable

Remarks

Note that event buffers are not thread-safe. It is not safe to write events to the buffer concurrently from multiple threads. It is, however, safe to traverse the contents of an existing buffer from multiple threads as long as it is not mutated at the same time.

Constructors

InputEventBuffer(NativeArray<Byte>, Int32, Int32, Boolean)

Construct an event buffer using the array containing InputEvents.

Declaration

public InputEventBuffer(NativeArray<byte> buffer, int eventCount, int sizeInBytes = -1, bool transferNativeArrayOwnership = false)

Parameters

Type	Name	Description
NativeArray<Byte>	buffer	A native array containing `eventCount` number of input events. The individual events in the buffer are variable-sized (depending on the type of each event).
Int32	eventCount	The number of events in `buffer`. Can be zero.
Int32	sizeInBytes	Total number of bytes of event data in the . If -1 (default), the size of the actual event data in `buffer` is considered unknown and has to be determined by walking `eventCount` number of events (due to the variable size of each event).
Boolean	transferNativeArrayOwnership	If true, ownership of the `NativeArray` given by `buffer` is transferred to the `InputEventBuffer`. Calling Dispose() will deallocate the array. Also, AllocateEvent(Int32, Int32, Allocator) may re-allocate the array.

Exceptions

Type	Condition
ArgumentException	`buffer` has no memory allocated but `eventCount` is not zero.
ArgumentOutOfRangeException	`sizeInBytes` is greater than the total length allocated for `buffer`.

InputEventBuffer(InputEvent*, Int32, Int32, Int32)

Construct an event buffer using the given memory block containing InputEvents.

Declaration

public InputEventBuffer(InputEvent*eventPtr, int eventCount, int sizeInBytes = -1, int capacityInBytes = -1)

Parameters

Type	Name	Description
InputEvent*	eventPtr	A buffer containing `eventCount` number of input events. The individual events in the buffer are variable-sized (depending on the type of each event).
Int32	eventCount	The number of events in `eventPtr`. Can be zero.
Int32	sizeInBytes	Total number of bytes of event data in the memory block pointed to by `eventPtr`. If -1 (default), the size of the actual event data in the buffer is considered unknown and has to be determined by walking `eventCount` number of events (due to the variable size of each event).
Int32	capacityInBytes	The total size of the memory block allocated at `eventPtr`. If this is larger than `sizeInBytes`, additional events can be appended to the buffer until the capacity is exhausted. If this is -1 (default), the capacity is considered unknown and no additional events can be appended to the buffer.

Exceptions

Type	Condition
ArgumentException	`eventPtr` is `null` and `eventCount` is not zero -or- `capacityInBytes` is less than `sizeInBytes`.

Fields

BufferSizeUnknown

Declaration

public const long BufferSizeUnknown = -1L

Field Value

Type	Description
Int64

Properties

bufferPtr

Pointer to the first event in the buffer.

Declaration

public readonly InputEventPtr bufferPtr { get; }

Property Value

Type	Description
InputEventPtr	Pointer to first event in buffer.

capacityInBytes

Total size of allocated memory in bytes. This value minus sizeInBytes is the spare capacity of the buffer. Will never be less than sizeInBytes.

Declaration

public readonly long capacityInBytes { get; }

Property Value

Type	Description
Int64	Size of allocated memory in bytes.

Remarks

A buffer's capacity determines how much event data can be written to the buffer before it has to be reallocated.

data

The raw underlying memory buffer.

Declaration

public readonly NativeArray<byte> data { get; }

Property Value

Type	Description
NativeArray<Byte>	Underlying buffer of unmanaged memory.

eventCount

Total number of events in the buffer.

Declaration

public readonly int eventCount { get; }

Property Value

Type	Description
Int32	Number of events currently in the buffer.

sizeInBytes

Size of the used portion of the buffer in bytes. Use capacityInBytes to get the total allocated size.

Declaration

public readonly long sizeInBytes { get; }

Property Value

Type	Description
Int64	Used size of buffer in bytes.

Remarks

If the size is not known, returns BufferSizeUnknown.

Note that the size does not usually correspond to eventCount times sizeof(InputEvent). as InputEvent instances are variable in size.

Methods

AllocateEvent(Int32, Int32, Allocator)

Make space for an event of sizeInBytes bytes and return a pointer to the memory for the event.

Declaration

public InputEvent*AllocateEvent(int sizeInBytes, int capacityIncrementInBytes = 2048, Allocator allocator = Allocator.Persistent)

Parameters

Type	Name	Description
Int32	sizeInBytes	Number of bytes to make available for the event including the event header (see InputEvent).
Int32	capacityIncrementInBytes	If the buffer needs to be reallocated to accommodate the event, number of bytes to grow the buffer by.
Allocator	allocator	If the buffer needs to be reallocated to accommodate the event, the type of allocation to use.

Returns

Type	Description
InputEvent*	A pointer to a block of memory in bufferPtr. Store the event data here.

Remarks

Only sizeInBytes is initialized by this method. No other fields from the event's header are touched.

The event will be appended to the buffer after the last event currently in the buffer (if any).

Exceptions

Type	Condition
ArgumentException	`sizeInBytes` is less than the size needed for the header of an InputEvent. Will automatically be aligned to a multiple of 4.

AppendEvent(InputEvent*, Int32, Allocator)

Append a new event to the end of the buffer by copying the event from eventPtr.

Declaration

public void AppendEvent(InputEvent*eventPtr, int capacityIncrementInBytes = 2048, Allocator allocator = Allocator.Persistent)

Parameters

Type	Name	Description
InputEvent*	eventPtr	Data of the event to store in the buffer. This will be copied in full as per sizeInBytes found in the event's header.
Int32	capacityIncrementInBytes	If the buffer needs to be reallocated to accommodate the event, number of bytes to grow the buffer by.
Allocator	allocator	If the buffer needs to be reallocated to accommodate the event, the type of allocation to use.

Remarks

If the buffer's current capacity (see capacityInBytes) is smaller than sizeInBytes of the given event, the buffer will be reallocated.

Exceptions

Type	Condition
ArgumentNullException	`eventPtr` is `null`.

Clone()

Declaration

public InputEventBuffer Clone()

Returns

Type	Description
InputEventBuffer

Contains(InputEvent*)

Whether the given event pointer refers to data within the event buffer.

Declaration

public bool Contains(InputEvent*eventPtr)

Parameters

Type	Name	Description
InputEvent*	eventPtr

Returns

Type	Description
Boolean

Remarks

Note that this method does NOT check whether the given pointer points to an actual event in the buffer. It solely performs a pointer out-of-bounds check.

Also note that if the size of the memory buffer is unknown (BufferSizeUnknown, only a lower-bounds check is performed.

Dispose()

Declaration

public void Dispose()

Implements

IDisposable.Dispose()

GetEnumerator()

Declaration

public IEnumerator<InputEventPtr> GetEnumerator()

Returns

Type	Description
IEnumerator<InputEventPtr>

Implements

IEnumerable<T>.GetEnumerator()

Reset()

Declaration

public void Reset()

Explicit Interface Implementations

IEnumerable.GetEnumerator()

Declaration

IEnumerator IEnumerable.GetEnumerator()

Returns

Type	Description
IEnumerator

Implements

IEnumerable.GetEnumerator()

ICloneable.Clone()

Declaration

object ICloneable.Clone()

Returns

Type	Description
Object

Implements

ICloneable.Clone()