class ByteBuffer in Tinman.Core.System

Represents a byte buffer.

sealed class

ByteBuffer

extends

Disposable

Remarks

The following figure illustrates the concepts used by a byte buffer:

+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+  Absolute byte offset
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | A | B | C | D | E | F |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+  Capacity = 16 bytes
          |                               |
     Position = 2                      Limit = 10
     (inclusive)                       (exclusive)
         \_____________________________/
          Buffer range, Remaining = 10-2 = 8

Byte order for multibyte data types is platform specific (e.g. little-endian for Intel x86).

The maximum capacity of a byte buffer is 2^31 bytes (i.e. 2 GB).

Configuration

ConfigByteOrder

The configurator object for this type.

public static readonly field	ConfigByteOrder
type	IConfigurator<ByteOrder>

Public / Attributes

Capacity

Capacity of this byte buffer, in bytes.

public property	Capacity { get }
type	int32
value	[>=0]	The buffer capacity, in bytes.

HasRemaining

Has this byte buffer some remaining bytes left (between current and limit position)?

public property	HasRemaining { get }
type	bool
value		true if there is at least one remaining byte, false if there are no bytes remaining.

IsRaw

Is this a raw byte buffer?

public property	IsRaw { get }
type	bool
value		true if this is a raw byte buffer, false if it is not.

Remarks:

Raw byte buffers are wrappers for memory regions that have been allocated by a third party (e.g. a locked vertex buffer region). The buffer itself does not hold ownership of the wrapped memory region and will hence perform no disposal whatsoever.

LifecycleState

Returns the lifecycle state of this object.

public virtual property	LifecycleState { get }
type	LifecycleState
value		The lifecycle state.
inherited	Disposable.LifecycleState

Limit

Gets or sets the buffer limit. If the position is larger than the new limit then it is set to the new limit.

public property	Limit { get set }
type	int32
value	[0..Capacity]	Byte index of new limit position.

NativeOrder

Returns the native byte order.

public static property	NativeOrder { get }
type	ByteOrder
value		The native byte order.

Position

Gets or sets the current position of this byte buffer.

public property	Position { get set }
type	int32
value	[0..Limit]	Byte index of new current position.

RawData

Sets the base pointer address of this byte buffer.

public property	RawData { get set }
type	IntPtr
value		The base pointer address.

Remarks:

Setting the base pointer of a byte buffer (only for raw buffers, see IsRaw) will reset the Position to zero and the Limit to the buffers Capacity.

RawLimit

Returns a memory pointer to the buffers current limit.

public property	RawLimit { get }
type	IntPtr
value		The memory pointer.

Remarks:

Use this property for interoperability with native code.

RawPosition

Returns a memory pointer to the buffers current position.

public property	RawPosition { get }
type	IntPtr
value		The memory pointer.

Remarks:

Use this property for interoperability with native code.

Remaining

Returns the number of bytes remaining between the current buffer position and its limit.

public property	Remaining { get }
type	int32
value	[>=0]	The number of remaining bytes.

Public / Constructors

Allocate

Allocates a new byte buffer.

[OwnerReturn]
public static method	Allocate (int32 size)
type	ByteBuffer
params	size	[>=0]	Size of the byte buffer, in bytes.
returns		[not-null]	The allocated byte buffer.

Remarks:

The Position of the newly created byte buffer will be zero and the Limit will be set to Capacity.

CreatePool

Creates an object pool for ByteBuffer objects of the given size.

[OwnerReturn]
public static method	CreatePool (string name, int32 bufferSize, int32 poolSize)
type	ByteBufferPool
params	name	[not-empty]	Name of the object pool.
	bufferSize	[>0]	The size of each byte buffer, in bytes.
	poolSize	[>0]	The maximum size of all byte buffers in the pool, in bytes.
returns		[not-null]	The object pool.

Raw

Creates a raw byte pointer buffer.

[OwnerReturn]
public static method	Raw (int32 size)
type	ByteBuffer
params	size	[>=0]	Size of buffer, in bytes.
returns		[not-null]	The raw byte buffer.

Remarks:

Raw byte buffer do not hold any real memory. They are placeholders for existing memory regions of the given size. The start address of a raw byte buffer must be specified via RawData.

Public / Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
public method	AcquireTry ()
type	IDisposable
returns			this if a new strong reference has been acquired, null if this object is already being disposed.
inherited	Disposable.AcquireTry

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls the AcquireTry method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Clear

Sets the position of this buffer to zero and the limit to its capacity.

public method	Clear ()
type	ByteBuffer
returns		[not-null]	this

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
public method	Dispose ()
inherited	Disposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

Flip

Flips the buffer by setting the limit to the current position and resetting the position to zero.

public method	Flip ()
type	ByteBuffer
returns		[not-null]	this

Get

Reads an 8-bit signed integer value from the current position and increases the position accordingly.

public method	Get ()
type	int8
returns			The read value.

---

Reads an 8-bit signed integer value from the given absolute position.

[Pure]
public method	Get (int32 position)
type	int8
params	position		The absolute position.
returns			The read value.

---

Reads bytes from this buffer and stores them in the given array.

public method	Get (int8[] buffer, int32 offset, int32 length)
params	buffer	[not-null]	The array where to store the bytes.
	offset	[0..buffer.Length]	Offset into buffer to first byte to store.
	length	[0..buffer.Length-offset]	Total number of bytes to store.

GetDouble

Reads a 64-bit floating point value from the current position and increases the position accordingly.

public method	GetDouble ()
type	float64
returns			The read value.

---

Reads a 64-bit floating point value from the given position.

[Pure]
public method	GetDouble (int32 position)
type	float64
params	position		The absolute position.
returns			The read value.

GetFloat

Reads a 32-bit floating point value from the current position and increases the position accordingly.

public method	GetFloat ()
type	float32
returns			The read value.

---

Reads a 32-bit floating point value from the given position.

[Pure]
public method	GetFloat (int32 position)
type	float32
params	position		The absolute position.
returns			The read value.

GetInt

Reads a 32-bit signed integer value from the current position and increases the position accordingly.

public method	GetInt ()
type	int32
returns			The read value.

---

Reads a 32-bit signed integer value from the given position.

[Pure]
public method	GetInt (int32 position)
type	int32
params	position		The absolute position.
returns			The read value.

GetLong

Reads a 64-bit signed integer value from the current position and increases the position accordingly.

public method	GetLong ()
type	int64
returns			The read value.

---

Reads a 64-bit signed integer value from the given position.

[Pure]
public method	GetLong (int32 position)
type	int64
params	position		The absolute position.
returns			The read value.

GetShort

Reads a 16-bit signed integer value from the current position and increases the position accordingly.

public method	GetShort ()
type	int16
returns			The read value.

---

Reads a 16-bit signed integer value from the given position.

[Pure]
public method	GetShort (int32 position)
type	int16
params	position		The absolute position.
returns			The read value.

PositionAndLimit

Sets the buffer position and limit.

public method	PositionAndLimit (int32 position, int32 relativeLimit = -1)
type	ByteBuffer
params	position	[0..Capacity]	The new buffer position.
	relativeLimit	[-1..Capacity-position]	The new buffer limit, relative to position. If -1, the buffer limit will be set to the capacity. Defaults to -1.
returns		[not-null]	this

Put

Writes an 8-bit signed integer value to the current position and increases the position accordingly.

public method	Put (int8 value)
params	value		The value to write.

---

Copies all bytes remaining in the given source buffer to this buffer.

public method	Put (ByteBuffer source)
params	source	[not-null]	The source byte buffer.

---

Writes an 8-bit signed integer value to the given position.

public method	Put (int32 position, int8 value)
params	position		The absolute position.
	value		The value to write.

---

Writes the given bytes into this buffer.

public method	Put (int8[] buffer, int32 offset, int32 length)
params	buffer	[not-null]	An array holding the bytes to write.
	offset	[0..buffer.Length]	Offset into buffer to first byte to write.
	length	[0..buffer.Length-offset]	Total number of bytes to write.

PutDouble

Writes a 64-bit floating point value to the current position and increases the position accordingly.

public method	PutDouble (float64 value)
params	value		The value to write.

---

Writes a 64-bit floating-point value to the given position.

public method	PutDouble (int32 position, float64 value)
params	position		The absolute position.
	value		The value to write.

PutFloat

Writes a 32-bit floating point value to the current position and increases the position accordingly.

public method	PutFloat (float32 value)
params	value		The value to write.

---

Writes a 32-bit floating-point value to the given position.

public method	PutFloat (int32 position, float32 value)
params	position		The absolute position.
	value		The value to write.

PutInt

Writes a 32-bit signed integer value to the current position and increases the position accordingly.

public method	PutInt (int32 value)
params	value		The value to write.

---

Writes a 32-bit signed integer value to the given position.

public method	PutInt (int32 position, int32 value)
params	position		The absolute position.
	value		The value to write.
returns		[not-null]	this

PutLong

Writes a 64-bit signed integer value to the current position and increases the position accordingly.

public method	PutLong (int64 value)
params	value		The value to write.

---

Writes a 64-bit signed integer value to the given position.

public method	PutLong (int32 position, int64 value)
params	position		The absolute position.
	value		The value to write.

PutShort

Writes a 16-bit signed integer value to the current position and increases the position accordingly.

public method	PutShort (int16 value)
params	value		The value to write.

---

Writes a 16-bit signed integer value to the given position.

public method	PutShort (int32 position, int16 value)
params	position		The absolute position.
	value		The value to write.

Zero

Fills a range of this buffer to 0.

public method	Zero (int32 position = -1, int32 count = -1)
type	ByteBuffer
params	position		Absolute offset of first buffer byte that will be filled. If less than 0, the current buffer Position will be used. Defaults to -1.
	count		Number of bytes to fill. If less than 0, all bytes up to the buffer Limit will be filled. Defaults to -1.
returns		[not-null]	this

Public / Extensions

CopyTo

Copies count bytes from the given source buffer into the target buffer.

method	CopyTo (ByteBuffer target, int32 count)
params	target	[not-null]	The target buffer.
	count	[>=0]	The number of bytes to copy.

Remarks:

The method will read count bytes from source, starting at the current buffer Position and will write them to target, beginning at the current buffer position. The current position of both source and target buffers will be incremented by count. The buffer limits will not be modified.

---

Copies count bytes from the given source buffer into the target buffer.

method	CopyTo (int32 sourcePosition, ByteBuffer target, int32 targetPosition, int32 count)
params	sourcePosition	[>=0]	Absolute position of first byte to read from source.
	target	[not-null]	The target buffer.
	targetPosition	[>=0]	Absolute position of first byte to write to target.
	count	[>=0]	The number of bytes to copy.

Remarks:

The method will read count bytes from source, starting at sourcePosition and will write them to target, beginning at targetPosition. The current buffer positions and limits of both source and target will not be modified.

Fill

Fills the remaining bytes in this buffer.

method	Fill (int8 value = 0)
type	ByteBuffer
params	value		The clear value. Defaults to 0.
returns		[not-null]	this

Remarks:

This method will not modify the Position and Limit of the buffer.

GetInt

Reads a signed 32-bit value from the given ByteBuffer using the given byte order.

method	GetInt (ByteOrder order)
type	int32
params	order		The byte order to use.
returns			The read value.

GetLong

Reads a signed 64-bit value from the given ByteBuffer using the given byte order.

method	GetLong (ByteOrder order)
type	int64
params	order		The byte order to use.
returns			The read value.

GetShort

Reads a signed 16-bit value from the given ByteBuffer using the given byte order.

method	GetShort (ByteOrder order)
type	int16
params	order		The byte order to use.
returns			The read value.

PutInt

Writes a signed 32-bit value to the given ByteBuffer using the given byte order.

method	PutInt (int32 value, ByteOrder order)
params	value		The value to write.
	order		The byte order to use.

PutLong

Writes a signed 64-bit value to the given ByteBuffer using the given byte order.

method	PutLong (int64 value, ByteOrder order)
params	value		The value to write.
	order		The byte order to use.

PutShort

Writes a signed 16-bit value to the given ByteBuffer using the given byte order.

method	PutShort (int16 value, ByteOrder order)
params	value		The value to write.
	order		The byte order to use.

ReadAsStream

Wraps this byte buffer in a data stream.

[OwnerReturn, OwnerThis]
method	ReadAsStream ()
type	MemoryDataStream
returns		[not-null]	The memory data stream.

Remarks:

This byte buffer will end up as the InternalBuffer of the returned MemoryDataStream object.

ToArray

Reads all remaining bytes from buffer and returns them as a byte array.

method	ToArray ()
type	int8[]
returns		[not-null]	The read bytes.

ToArrayOwn

Reads all remaining bytes from buffer and returns them as a byte array.

[OwnerThis]
method	ToArrayOwn ()
type	int8[]
returns		[not-null]	The read bytes.