# class FieldData

FieldData represents multiple fields of data. Each field is implemented as an ValueArray object, that has a unique name, and can have complex components (such as scalars, vectors, quaternions, tensors or matrices). All fields are assumed to be of the same length. IFieldData can be seen as an array with complex tuples, where the component can be of different types.

# Properties

Property Description
TupleCount Resizes/Gets the list to the specified tuplecount. If the list is enlarged, the new tuples will contain unspecified data.

# Methods

Method Description
AddBaseTypeField Adds a field based on a base type. Only ValueArray objects are allowed. The created and added object is returned.
AddField Adds a field. The field must have a unique name set.
AddTupleCount Adds a number of tuples to the current tuple count.
AppendTuples Appends another field data object to this object. The fields are allowed to be setup differently, but then comes at a significant performance penalty. If fields in the other field data object is missing in this object, these will be added, and the items in the old tuples will be set to 0.
Clear Clears all tuples from the fields. The fields, however, are not removed.
CopyCombine3Tuples CopyCombine3Tuples combines the data from three tuples into a destination tuple. The call works like CobineTuples, but there is three source tuples, and two alpha values. the destination will be weighted by the values: alpha_3 = 1-(alpha_1 + alpha_2) dest = src_1*alpha_1 + src_2*alpha_2 + src_3*alpha_3 This field data object can be used as the source field data object to copy within the object.
CopyCombineTuples CopyCombineTuples() combines the data from two tuples into a destination tuple. This field data object can be used as the source field data object to copy within the object.
CopyRange CopyRange() copies a range of tuples from a source field object into this field object. The field objects must have the same field setup. This field object must be resized to hold the tuples before copying.
CopyTuple CopyTuple() copies one tuple to another. Both the dest_id and the source_id must exist in the array. This field data object can be used as the source field data object to copy within the object.
DeepCopy Copies the field setup and data from another object. To only copy the setup, set copy_data to false.
ExtractTuples Extracts a range of tuples from this object. The receiving object is assumed to have exactly the same data fields as this object.
GetClass Get the name of the FieldData class.
GetField Retrieves a field. If the field was not found, null is returned.
GetFieldCount Returns the number of fields in the field data object. The ids of the fields range from 0 through (GetFieldCount()-1).
GetFieldWithHandle Returns the field associated with the specified handle.
GetFieldWithId Retrieves a field from its index in the field data.
GetFirstFieldHandle Returns the handle of the first field, or null if no fields are added to the object.
GetMaxFieldId Returns the id of the field with the highest id. NOTE! If no fields exist in the field data object, the return is undefined.
GetMaxTupleId Returns the id of the last tuple in the array. If the array is empty, the value is undefined.
GetNextFieldHandle Returns the next handle, or null if no more fields exist in the object.
IndexedCombine Works like IndexedCopy, but uses two consecutive ids in the idtable, and a blend value from the blendtable. The idtable contains (idtable_cnt*2) indices and blendtable contains idtable_cnt blend values. Does the blend: dest = src1*(1-blend) + src2*blend The FieldData must have enough tuples to hold the new data.
IndexedCombine3 Works like IndexedCombine(), but with three ids that are combined through two blend values in the blendtable. The idtable contains (idtable_cnt*3) indices and blendtable contains (idtable_cnt*2) blend values. Does the blend: dest = src1*blend1 + src2*blend2 + src3*(1-(blend1+blend2)) The FieldData must have enough tuples to hold the new data.
IndexedCopy Copies tuples from a source field data object through an id table. The id table dictates the order in which the tuples are to be copied. E.g. If the first item in the id table has the value 14, then the tuple with id 14 in the source array will be copied to the first tuple in this array. Note! All ids in the id table must be valid ids of tuples in the source field data object. The id table is assumed to have a tuple size of 1. The source and this field data object must have the same underlaying data fields, of the same type and the same tuple sizes. The FieldData must have enough tuples to hold the new data.
IsA Returns true if FieldData is a or is a descendant of the class named as the type parameter.
IsEmpty Returns 1 if no tuples exist in the field data.
IsNull Returns true if the FieldData object is invalid.
IsSetupIdenticalTo Compares the field setup of this field data object to another field data object. If the setups are not identical, false is returned. Note! IsSetupIdenticalTo will return false even if the same fields exist in both field data objects, but are not in the same order.
NewCopy Creates another field data object with the same field setup. To also copy the data to the new object, set copy_data to true.
NewPackedCopy Like NewCopy, NewPackedCopy creates a field data object with the same underlying data and tuple settings as the source field data object. However, NewPackedCopy only copies unique tuples, and if the index_array parameter is set, this index array will contain the same number of tuples as the source field data object, and with the ids of a specific tuples within the new copy of the field data object.
RemoveAllFields Clears all fields from the object. Releases all data in the object.
RemoveField Removes a field. Removing a field causes the remaining fields to be remapped to new ids. Note that the field must exist. If not, the method will return error. To remove a field that may not exist, use SafeRemoveField.
SafeRemoveField Removes a field. Removing a field causes the remaining fields to be remapped to new ids.

# Static methods

Method Description
IsClassA Returns true if the class is a or is a descendant of the class named as the type parameter.
SafeCast SafeCast makes sure the input object is of a class that can be cast into spFieldData, and if this is the case, returns the object cast into spFieldData.

# Properties details

# TupleCount

Resizes/Gets the list to the specified tuplecount. If the list is enlarged, the new tuples will contain unspecified data.

# Syntax

// Setter
void SetTupleCount( unsigned int tuplecount );

// Getter
unsigned int GetTupleCount();

# SetTupleCount parameters

Type Name Min Max Description
unsigned int tuplecount 0 INT_MAX The desired tuple count.

# GetTupleCount return value

Type: unsigned int

# Methods details

# AddBaseTypeField

Adds a field based on a base type. Only ValueArray objects are allowed. The created and added object is returned.

# Syntax

spValueArray AddBaseTypeField( Simplygon::EBaseTypes base_type , unsigned int tuple_size , const char * name );

# Parameters

Type Name Min Max Description
EBaseTypes base_type Should be a base type listed in BaseTypes.
unsigned int tuple_size The desired tuple size.
const char * name The name of the new field.

# Return value

Type: ValueArray

# AddField

Adds a field. The field must have a unique name set.

# Syntax

void AddField( spValueArray field );

# Parameters

Type Name Min Max Description
ValueArray field The array to add to the field data.

# AddTupleCount

Adds a number of tuples to the current tuple count.

# Syntax

void AddTupleCount( unsigned int tuplecount );

# Parameters

Type Name Min Max Description
unsigned int tuplecount 0 INT_MAX The desired number of tuples to add. Note that the total TupleCount cannot exceed INT_MAX.

# AppendTuples

Appends another field data object to this object. The fields are allowed to be setup differently, but then comes at a significant performance penalty. If fields in the other field data object is missing in this object, these will be added, and the items in the old tuples will be set to 0.

# Syntax

void AppendTuples( spFieldData other , bool add_missing_fields );

# Parameters

Type Name Min Max Description
FieldData other The field data object that is appended.
bool add_missing_fields If set to true, missing fields will be added to this field data object.

# Clear

Clears all tuples from the fields. The fields, however, are not removed.

# Syntax

void Clear();

# Parameters

Clear takes no parameters.

# CopyCombine3Tuples

CopyCombine3Tuples combines the data from three tuples into a destination tuple. The call works like CobineTuples, but there is three source tuples, and two alpha values. the destination will be weighted by the values: alpha_3 = 1-(alpha_1 + alpha_2) dest = src_1*alpha_1 + src_2*alpha_2 + src_3*alpha_3 This field data object can be used as the source field data object to copy within the object.

# Syntax

void CopyCombine3Tuples( spFieldData source , rid dest_id , rid src_id_1 , rid src_id_2 , rid src_id_3 , real alpha_1 , real alpha_2 );

# Parameters

Type Name Min Max Description
FieldData source The field data source to combine from.
rid dest_id The tuple index to put the combined results into in this field data.
rid src_id_1 The first tuple index to use for combining from the field data source.
rid src_id_2 The second tuple index to use for combining from the field data source.
rid src_id_3 The third tuple index to use for combining from the field data source.
real alpha_1 The first interpolation value used for combining the source tuples.
real alpha_2 The second interpolation value used for combining the source tuples.

# CopyCombineTuples

CopyCombineTuples() combines the data from two tuples into a destination tuple. This field data object can be used as the source field data object to copy within the object.

# Syntax

void CopyCombineTuples( spFieldData source , rid dest_id , rid src_id_1 , rid src_id_2 , real alpha );

# Parameters

Type Name Min Max Description
FieldData source The field data source to combine from.
rid dest_id The tuple index to put the combined results into in this field data.
rid src_id_1 The first tuple index to use for combining from the field data source.
rid src_id_2 The second tuple index to use for combining from the field data source.
real alpha The interpolation value used for combining the source tuples.

# CopyRange

CopyRange() copies a range of tuples from a source field object into this field object. The field objects must have the same field setup. This field object must be resized to hold the tuples before copying.

# Syntax

void CopyRange( spFieldData source , rid start_dest_id , rid start_src_id , unsigned int count );

# Parameters

Type Name Min Max Description
FieldData source The source field object to copy from.
rid start_dest_id The first destination tuple id.
rid start_src_id The first source tuple id.
unsigned int count The number of tuples to copy.

# CopyTuple

CopyTuple() copies one tuple to another. Both the dest_id and the source_id must exist in the array. This field data object can be used as the source field data object to copy within the object.

# Syntax

void CopyTuple( spFieldData source , rid dest_id , rid src_id );

# Parameters

Type Name Min Max Description
FieldData source The source field data to copy from.
rid dest_id The tuple index to copy into in this field data.
rid src_id The tuple index to copy from in the source field data.

# DeepCopy

Copies the field setup and data from another object. To only copy the setup, set copy_data to false.

# Syntax

void DeepCopy( spFieldData source , bool copy_data );

# Parameters

Type Name Min Max Description
FieldData source The source array to copy from.
bool copy_data True if the data should be copied along with the field data properties.

# ExtractTuples

Extracts a range of tuples from this object. The receiving object is assumed to have exactly the same data fields as this object.

# Syntax

void ExtractTuples( spFieldData dest , rid start , unsigned int count );

# Parameters

Type Name Min Max Description
FieldData dest The destination object.
rid start The id of the first tuple that is extracted.
unsigned int count The number of tuples to extract.

# GetClass

Get the name of the FieldData class.

# Syntax

spString GetClass();

# Parameters

GetClass takes no parameters.

# Return value

Type: spString

# GetField

Retrieves a field. If the field was not found, null is returned.

# Syntax

spValueArray GetField( const char * name );

# Parameters

Type Name Min Max Description
const char * name The name of the field to fetch.

# Return value

Type: ValueArray

# GetFieldCount

Returns the number of fields in the field data object. The ids of the fields range from 0 through (GetFieldCount()-1).

# Syntax

unsigned int GetFieldCount();

# Parameters

GetFieldCount takes no parameters.

# Return value

Type: unsigned int

# GetFieldWithHandle

Returns the field associated with the specified handle.

# Syntax

spValueArray GetFieldWithHandle( rhandle hand );

# Parameters

Type Name Min Max Description
rhandle hand The handle to the requested field.

# Return value

Type: ValueArray

# GetFieldWithId

Retrieves a field from its index in the field data.

# Syntax

spValueArray GetFieldWithId( rid id );

# Parameters

Type Name Min Max Description
rid id The id of the field.

# Return value

Type: ValueArray

# GetFirstFieldHandle

Returns the handle of the first field, or null if no fields are added to the object.

# Syntax

rhandle GetFirstFieldHandle();

# Parameters

GetFirstFieldHandle takes no parameters.

# Return value

Type: rhandle

# GetMaxFieldId

Returns the id of the field with the highest id. NOTE! If no fields exist in the field data object, the return is undefined.

# Syntax

rid GetMaxFieldId();

# Parameters

GetMaxFieldId takes no parameters.

# Return value

Type: rid

# GetMaxTupleId

Returns the id of the last tuple in the array. If the array is empty, the value is undefined.

# Syntax

rid GetMaxTupleId();

# Parameters

GetMaxTupleId takes no parameters.

# Return value

Type: rid

# GetNextFieldHandle

Returns the next handle, or null if no more fields exist in the object.

# Syntax

rhandle GetNextFieldHandle( rhandle hand );

# Parameters

Type Name Min Max Description
rhandle hand The current handle.

# Return value

Type: rhandle

# IndexedCombine

Works like IndexedCopy, but uses two consecutive ids in the idtable, and a blend value from the blendtable. The idtable contains (idtable_cnt*2) indices and blendtable contains idtable_cnt blend values. Does the blend: dest = src1*(1-blend) + src2*blend The FieldData must have enough tuples to hold the new data.

# Syntax

void IndexedCombine( spFieldData source , spRidArray idtable , spRealArray blendtable , rid startId );

# Parameters

Type Name Min Max Description
FieldData source The field data to combine from.
RidArray idtable Array containing the tuple indices to combine.
RealArray blendtable Array containing the blend weights.
rid startId The tuple to begin putting the combinations into.

# IndexedCombine3

Works like IndexedCombine(), but with three ids that are combined through two blend values in the blendtable. The idtable contains (idtable_cnt*3) indices and blendtable contains (idtable_cnt*2) blend values. Does the blend: dest = src1*blend1 + src2*blend2 + src3*(1-(blend1+blend2)) The FieldData must have enough tuples to hold the new data.

# Syntax

void IndexedCombine3( spFieldData source , spRidArray idtable , spRealArray blendtable , rid startId );

# Parameters

Type Name Min Max Description
FieldData source The field data to combine from.
RidArray idtable Array containing the tuple indices to combine.
RealArray blendtable Array containing the blend weights.
rid startId The tuple to begin putting the combinations into.

# IndexedCopy

Copies tuples from a source field data object through an id table. The id table dictates the order in which the tuples are to be copied. E.g. If the first item in the id table has the value 14, then the tuple with id 14 in the source array will be copied to the first tuple in this array. Note! All ids in the id table must be valid ids of tuples in the source field data object. The id table is assumed to have a tuple size of 1. The source and this field data object must have the same underlaying data fields, of the same type and the same tuple sizes. The FieldData must have enough tuples to hold the new data.

# Syntax

void IndexedCopy( spFieldData source , spRidArray idtable , rid startId );

# Parameters

Type Name Min Max Description
FieldData source The source field data object to copy from.
RidArray idtable Array containing the tuple indices to copy.
rid startId The first tuple to begin copy into.

# IsA

Returns true if FieldData is a or is a descendant of the class named as the type parameter.

# Syntax

bool IsA( const char * type );

# Parameters

Type Name Min Max Description
const char * type Name of the class to check if FieldData is, or is a descendant of.

# Return value

Type: bool

# IsEmpty

Returns 1 if no tuples exist in the field data.

# Syntax

int IsEmpty();

# Parameters

IsEmpty takes no parameters.

# Return value

Type: int

# IsNull

Returns true if the FieldData object is invalid.

# Syntax

bool IsNull();

# Parameters

IsNull takes no parameters.

# Return value

Type: bool

# IsSetupIdenticalTo

Compares the field setup of this field data object to another field data object. If the setups are not identical, false is returned. Note! IsSetupIdenticalTo will return false even if the same fields exist in both field data objects, but are not in the same order.

# Syntax

bool IsSetupIdenticalTo( spFieldData other );

# Parameters

Type Name Min Max Description
FieldData other The other field data object used for comparison.

# Return value

Type: bool

# NewCopy

Creates another field data object with the same field setup. To also copy the data to the new object, set copy_data to true.

# Syntax

spFieldData NewCopy( bool copy_data );

# Parameters

Type Name Min Max Description
bool copy_data True if data should be copied along with the field properties.

# Return value

Type: FieldData

# NewPackedCopy

Like NewCopy, NewPackedCopy creates a field data object with the same underlying data and tuple settings as the source field data object. However, NewPackedCopy only copies unique tuples, and if the index_array parameter is set, this index array will contain the same number of tuples as the source field data object, and with the ids of a specific tuples within the new copy of the field data object.

# Syntax

spFieldData NewPackedCopy( spRidArray index_array );

# Parameters

Type Name Min Max Description
RidArray index_array Will contain indices to the new packed field data values.

# Return value

Type: FieldData

# RemoveAllFields

Clears all fields from the object. Releases all data in the object.

# Syntax

void RemoveAllFields();

# Parameters

RemoveAllFields takes no parameters.

# RemoveField

Removes a field. Removing a field causes the remaining fields to be remapped to new ids. Note that the field must exist. If not, the method will return error. To remove a field that may not exist, use SafeRemoveField.

# Syntax

void RemoveField( const char * name );

# Parameters

Type Name Min Max Description
const char * name The name of the field.

# SafeRemoveField

Removes a field. Removing a field causes the remaining fields to be remapped to new ids.

# Syntax

void SafeRemoveField( const char * name );

# Parameters

Type Name Min Max Description
const char * name The name of the field.

# Static methods details

# IsClassA

Returns true if the class is a or is a descendant of the class named as the type parameter.

# Syntax

static bool IsClassA( const char * type );

# Parameters

Type Name Min Max Description
const char * type Name of the class to check if the class is, or is a descendant of.

# Return value

Type: bool

# SafeCast

SafeCast makes sure the input object is of a class that can be cast into spFieldData, and if this is the case, returns the object cast into spFieldData.

# Syntax

static spFieldData SafeCast( spObject object );

# Parameters

Type Name Min Max Description
Object object Object to cast.

# Return value

Type: FieldData