TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

class ByteBuffer in Tinman.Core.System

Represents a byte buffer.

sealed class ByteBuffer extends Disposable
  implements IDisposableGeneric<ByteBuffer>

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 multi-byte 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 property ConfigByteOrder { get }
type IConfigurator<ByteOrder>
value [not-null] The configurator object.

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.

IsCompact

Is this buffer compact?

public property IsCompact { get }
type bool
value true if this buffer is compact, false if not.

Remarks:

A compact buffer has a Position of 0, and its Limit is equal to its Capacity.

See also:

Compact

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.

IsSoleOwnership

Will this object be disposed upon the next call to Dispose?

[ThreadSafe]
public property IsSoleOwnership { get }
type bool
value true if the object will be disposed when Dispose is called,
false if the object will not be disposed, because some other code is still holding shared ownership (see AcquireThrow).
inherited Disposable.IsSoleOwnership

LifecycleState

Returns the lifecycle state of this object.

public 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, panicking if not enough memory is available.

[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.

See also:

TinmanException.Panic

AllocateNull

Allocates a new byte buffer, returning null if not enough memory is available.

[OwnerReturn]
public static method AllocateNull (int32 size)
type ByteBuffer
params size [>=0] Size of the byte buffer, in bytes.
returns The allocated byte buffer or null iff not enough memory is available.

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.

FromArray

Creates a new instance of ByteBuffer from the given byte array.

[OwnerReturn]
public static method FromArray (int8[] array, int32 offset = 0, int32 length = -1)
type ByteBuffer
params array [not-null] The byte array to copy bytes from.
  offset [>=0] Offset into array to first byte to copy. Defaults to 0.
  length [-1..array.Length-offset] Number of bytes to copy. If -1 all bytes in array from offset to the end will be copied. Defaults to -1.
returns [not-null] The created ByteBuffer object.

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

Acquire

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public method Acquire ()
type ByteBuffer
returns The strong reference to this disposable object or null iff this object is no longer valid.

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls this 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.

AcquireBase

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public method AcquireBase ()
type IDisposable
returns The strong reference to this disposable object or null iff this object is no longer valid.
inherited Disposable.AcquireBase

Remarks:

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

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

Using this method usually requires type casting. Subclasses may additionally implement IDisposableGeneric, in order to provide some syntactic sugar for that.

AcquireThrow

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public method AcquireThrow ()
type IDisposable
returns [not-null] The strong reference to this disposable object.
inherited Disposable.AcquireThrow

Remarks:

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

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

Exceptions:

Clear

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

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

Compact

Returns a compact ByteBuffer that contains the data of this ByteBuffer between its current Position and Limit.

[OwnerReturn, OwnerThis]
public method Compact ()
type ByteBuffer
returns The compact byte buffer. Will be this iff IsCompact returns true, otherwise a new ByteBuffer is returned.

See also:

IsCompact

Copy

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

public method Copy (int32 sourcePosition, ByteBuffer target, int32 targetPosition, int32 count)
params sourcePosition [>=0] Absolute position of first byte to read from this source buffer.
  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 this source buffer, starting at sourcePosition and will write them to the given target buffer, beginning at targetPosition. The current buffer positions and limits of both buffers will not be modified.

Copying between raw byte buffers is not allowed (see IsRaw).

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.

Implementing methods must not throw any exceptions.

Fill

Fills the remaining bytes in this buffer.

public 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 ByteBuffer and ByteBuffer of the buffer.

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.

GetBytes

Copies count bytes from this source buffer to the given target buffer.

public method GetBytes (ByteBuffer target, int32 count = -1)
params target [not-null] The target buffer.
  count [>=-1] The number of bytes to copy. If -1, the number of remaining bytes in this source buffer will be used. Defaults to -1.

Remarks:

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

Copying between raw byte buffers is not allowed (see IsRaw).


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

public method GetBytes (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 signed 32-bit value from from this buffer using the given byte order.

public method GetInt (ByteOrder order)
type int32
params order The byte order to use.
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 signed 64-bit value from from this buffer using the given byte order.

public method GetLong (ByteOrder order)
type int64
params order The byte order to use.
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 signed 16-bit value from this buffer using the given byte order.

public method GetShort (ByteOrder order)
type int16
params order The byte order to use.
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.

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.

PutBytes

Copies count bytes from the given source buffer to this target buffer.

public method PutBytes (ByteBuffer source, int32 count = -1)
params source [not-null] The source buffer.
  count [>=-1] The number of bytes to copy. If -1, the number of remaining bytes in the source buffer will be used. Defaults to -1.

Remarks:

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

Copying between raw byte buffers is not allowed (see IsRaw).


Writes the given bytes into this buffer.

public method PutBytes (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 signed 32-bit value to this buffer using the given byte order.

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

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.

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 signed 64-bit value to this buffer using the given byte order.

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

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 signed 16-bit value to this buffer using the given byte order.

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

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.

ReadAsStream

Wraps this byte buffer in a data stream.

[OwnerReturn, OwnerThis]
public 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.

Skip

Skips bytes by incrementing Position, without reading from or writing to memory.

public method Skip (int32 count)
params count [>=0] The number of bytes to skip.

ToArray

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

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

ToArrayOwn

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

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

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