OxMVector3Array Class
This class holds an array of single-precision 3D vectors suitable for use as 3D vertex positions, normals, colors, etc. The advantage of this class over a standard REALbasic Array is fast and automatic conversion to Ptr for use in declare statements. The advantage over a standard Memoryblock is a concise API that only deals with one data type, and efficient bulk-math operations.
Important: Some OxMVector3Array methods accept or return OxMVector3 instances, but keep in mind that OxMVector3 uses double-precision floats while this class uses single-precision. This shouldn't cause problems under normal circumstances but it's a detail to be aware of, as the values of vectors passed into and out of this class may not exactly match their original values.
Note: This class may resemble a Memoryblock in some respects but keep in mind that it lacks a LittleEndian flag, and the data accessors do not perform any sort of byte swapping. The internal data storage always uses the current platform's native endianness, however, a Copy method that accepts a Memoryblock is provided that will byte-swap the Memoryblock's data when necessary.
Constructors
-
OxMVector3Array ( numelements As Integer )
Initializes the array to the hold the requested number of vectors. Pass zero to initialize the array without allocating memory.
Important: Although element indexes are zero-based the numelements parameter is the total number of elements required, not the upper-bound as used when initializing a REALbasic array.
Constants
-
kElementSize = 12
The byte size of one array element - i.e. three Single values (3 * 4 bytes). This is provided for advanced users wishing to manipulate the data block with direct Ptr access.
Properties
-
Count As Integer
Read or set the number of vectors in the array.
Methods
-
Add ( va As OxMVector3Array )
Adds each vector in the passed array to the corresponding vector in this array.
Important: va must be the same size or larger than this array. If va is larger the overflow will be ignored, if it's smaller an OutOfBoundsException will occur (so long as OxMath error checking is enabled). -
Add ( n As Single )
Adds the scalar n to each vector in this array. -
Clear
Sets all vectors to zero. -
Copy As OxMVector3Array
Returns a copy of this vector array. -
Copy ( source As MemoryBlock )
Copies the byte data in the passed Memoryblock into this array, resizing the vector array as needed. The source Memoryblock must be a sized block, not a Ptr, and bytes will be swapped as needed if the Memoryblock's LittleEndian flag does not match the current platform's endianness.
Important: This method is provided to easily copy data loaded from disk into the vector array. The data in the Memoryblock is treated as a series 3D single-precision vector elements, and will be truncated to a multiple of kElementSize if it overflows. -
Copy ( source As OxMVector3Array )
Copies the data in the passed vector array into this vector array, resizing this array to match (if needed). -
CopyBestFit ( source As OxMVector3Array )
Copies the data in the passed vector array into this vector array, without resizing this array. If the passed array is smaller the overflow is left untouched, if the passed array is larger, the overflow is ignored. This method is faster than the regular Copy and doesn't require a memory re-allocation, but is mostly only useful for copying equally sized arrays. -
GetVector ( idx As Integer ) OxMVector3
Returns a copy of the vector at the requested index as an OxMVector3 instance. -
GetVector ( idx As Integer, vec As OxMVector3 )
Copies the vector at the requested index into the passed OxMVector3 instance. -
Interpolate ( va1 As OxMVector3Array, va2 As OxMVector3Array, alpha As Single )
Performs the equation va1 + alpha * (va2 - va1) for each vector and stores the result in this array. This can be used to "morph" one set of vectors into another set.
Important: va1 and va2 must be the same size or larger than this array. If either are larger the overflow will be ignored, if either are smaller an OutOfBoundsException will occur (so long as OxMath error checking is enabled). -
Multiply ( va As OxMVector3Array )
Multiplies each vector in this array by the corresponding vector in the passed array.
Important: va must be the same size or larger than this array. If va is larger the overflow will be ignored, if it's smaller an OutOfBoundsException will occur (so long as OxMath error checking is enabled). -
Multiply ( n As Single )
Multiplies each vector in this array by the scalar n. -
Normalize
Scales each vector in this array to unit length (1.0). -
SetToDifference ( va1 As OxMVector3Array, va2 As OxMVector3Array )
Subtracts each vector in va2 from the corresponding vector in va1 and stores the result in this array.
Important: va1 and va2 must be the same size or larger than this array. If either are larger the overflow will be ignored, if either are smaller an OutOfBoundsException will occur (so long as OxMath error checking is enabled). -
SetToDifference ( va As OxMVector3Array, n As Single )
Subtracts the scalar n from each vector in va and stores the result in this array.
Important: va must be the same size or larger than this array. If va is larger the overflow will be ignored, if it's smaller an OutOfBoundsException will occur (so long as OxMath error checking is enabled). -
SetToProduct ( va1 As OxMVector3Array, va2 As OxMVector3Array )
Multiplies each vector in va1 by the corresponding vector in va2 and stores the result in this array.
Important: va1 and va2 must be the same size or larger than this array. If either are larger the overflow will be ignored, if either are smaller an OutOfBoundsException will occur (so long as OxMath error checking is enabled). -
SetToProduct ( va As OxMVector3Array, n As Single )
Multiplies each vector in va by the scalar n and stores the result in this array.
Important: va must be the same size or larger than this array. If va is larger the overflow will be ignored, if it's smaller an OutOfBoundsException will occur (so long as OxMath error checking is enabled). -
SetToSum ( va1 As OxMVector3Array, va2 As OxMVector3Array )
Adds each vector in va1 to the corresponding vector in va2 and stores the result in this array.
Important: va1 and va2 must be the same size or larger than this array. If either are larger the overflow will be ignored, if either are smaller an OutOfBoundsException will occur (so long as OxMath error checking is enabled). -
SetToSum ( va As OxMVector3Array, n As Single )
Adds the scalar n to each vector in va and stores the result in this array.
Important: va must be the same size or larger than this array. If va is larger the overflow will be ignored, if it's smaller an OutOfBoundsException will occur (so long as OxMath error checking is enabled). -
SetVector ( idx As Integer, vec As OxMVector3 )
Sets the vector at the requested index to a copy of the passed vector. -
SetVector ( idx As Integer, X As Single, Y As Single, Z As Single )
Sets the vector at the requested index using three Single values. -
Subtract ( va As OxMVector3Array )
Subtracts each vector in the passed array from the corresponding vector in this array.
Important: va must be the same size or larger than this array. If va is larger the overflow will be ignored, if it's smaller an OutOfBoundsException will occur (so long as OxMath error checking is enabled). -
Subtract ( n As Single )
Subtracts the scalar n from each vector in in this array. -
X ( idx As Integer ) As Single
Read or set the X component of the vector at the requested index. -
Y ( idx As Integer ) As Single
Read or set the Y component of the vector at the requested index. -
Z ( idx As Integer ) As Single
Read or set the Z component of the vector at the requested index.