ChangeVertexColorDatatype

Adds a Vertex Color Change Datatype operator on the specified VertexColor property. Vertex color properties now support two internal data representations for colors: Short (8-bits colors) or Float (32-bits). RenderMaps can be set to bake 32-bit colors into the CAVs, but the CAVs can also be changed after the fact to 8-bit or 32-bit colors. This would allow, for example, a user to write and read 32-bit precision colors in and from the CAV, using the SDK.

The Vertex Color Change Datatype operator allows you to modify the "datatype" parameter which is normally read-only, and so cannot be changed via SetValue, Parameter.Value, or Parameter.PutValue2. The JScript example below demonstrates this principle.

The DesiredDatatype input parameter is required. If the current VertexColor property already uses the desired datatype, then a warning message is logged and no operator is installed.

Typically, you call this command just once to apply the Vertex Color Change Datatype operator. Then, if you need to change the "datatype" setting again, you can just access the "desireddatatype" parameter on the operator, instead of applying another operator with this command. As the JScript example below demonstrates, if you have several operators applied on the same VertexColor property, you need to be careful that you are modifying the "desireddatatype" parameter on the correct operator.

1. JScript Example

/*

	This example demonstrates how to set the read-only DataType on a VertexColor (CAV) property, including 

	avoiding some of the pitfalls of applying more than one Vertex Color Change Datatype operator.

*/

NewScene( "", false );

var obj = Application.ActiveSceneRoot.AddGeometry( "Cube", "MeshSurface" );

var VtxColors = CreateVertexColorSupport( null, null, obj );

// Get the datatype parameter (on the VertexColor property)

var DataType = VtxColors(0).Parameters("datatype");

Application.LogMessage( "Default DataType: " + DataType.Value );

// The datatype parameter is readonly

try {

	// This will throw an error

	DataType.Value = 1;

} catch(e) {

	Application.LogMessage( "Error on DataType.Value = 1: " + e.description, siWarning );

	try {

		// SetValue will also fail

		SetValue( DataType, 1 );

	} catch(f) {

		Application.LogMessage( "Error on SetValue( DataType, 1 ): " + f.description, siWarning );

	}

}

// Use the VertexColorChangeDatatype operator instead

var DataChgOps1 = ChangeVertexColorDatatype( VtxColors, 1 );

var DesiredDType1 = DataChgOps1(0).Parameters("desireddatatype");

Application.LogMessage( "DataType after 1st operator: " + DataType.Value );

// Now that you have the VertexColorChangeDatatype operator, you can 

// use its DesiredDatatype parameter to toggle back and forth

DesiredDType1.Value = 0;

Application.LogMessage( "Back to default: " + DataType.Value );

DesiredDType1.Value = 1;

Application.LogMessage( "Switched to float again: " + DataType.Value );

// However, if you try to apply another operator, only the last one 

// applied will affect the actual data type

var DataChgOps2 = ChangeVertexColorDatatype( VtxColors, 0 );

var DesiredDType2 = DataChgOps2(0).Parameters("desireddatatype");

Application.LogMessage( "DataType after 2nd operator: " + DataType.Value );

DesiredDType1.Value = 1;

Application.LogMessage( "Changed old operator: " + DataType.Value );

DesiredDType2.Value = 1;

Application.LogMessage( "Changed new operator: " + DataType.Value );

// For the truly cautious, get the last operator applied

var CAVProp = obj.ActivePrimitive.Geometry.VertexColors(0);

var LastChgDataTypeOp;

for ( var i=CAVProp.NestedObjects.Count-1; i>=0; i++ ) {

	if ( CAVProp.NestedObjects.Item(i).Type == "vertexcolorchangedatatype" ) {

		LastChgDataTypeOp = CAVProp.NestedObjects.Item(i);

		break;

	}

}

Application.LogMessage( "LastChgDataTypeOp == DataChgOps1: " + LastChgDataTypeOp.IsEqualTo(DataChgOps1(0)) );

Application.LogMessage( "LastChgDataTypeOp == DataChgOps2: " + LastChgDataTypeOp.IsEqualTo(DataChgOps2(0)) );

var LastDesiredDType = LastChgDataTypeOp.Parameters("desireddatatype");

LastDesiredDType.Value = 0;

Application.LogMessage( "Changed final operator: " + DataType.Value );

// Output:

// INFO : Default DataType: 0

// WARNING : 2011 - Error on DataType.Value = 1: Member not found

// ERROR : 2011-EDIT-SetValue - Member not found

// WARNING : Error on SetValue( DataType, 1 ): Object doesn't support this property or method

// INFO : DataType after 1st operator: 1

// INFO : Back to default: 0

// INFO : Switched to float again: 1

// INFO : DataType after 2nd operator: 0

// INFO : Changed old operator: 0

// INFO : Changed new operator: 1

// INFO : LastChgDataTypeOp == DataChgOps1: false

// INFO : LastChgDataTypeOp == DataChgOps2: true

// INFO : Changed final operator: 0

2. VBScript Example

'

' This example creates a Vertex Color property (CAV) and plays with one of the colors 

' to demonstrate how switching the datatype can affect the color values

'

dim CAVObjs, dtype, chgOp, aColors

NewScene , false

SetDisplayMode "Camera", "constant"

CreatePrim "Sphere", "MeshSurface"

' The VertexColor property is the first element in the returned collection

set CAVObj = CreateVertexColorSupport()(0)

set dtype = CAVObj.Parameters("datatype")

' Print current datatype

Application.LogMessage "CAV datatype = " & dtype.Value

' Change datatype to float and print new datatype

set chgOp = ChangeVertexColorDatatype( CAVObj, 1 )(0)

Application.LogMessage "CAV new datatype = " & dtype.Value

' Set Color 47 (facing front view) to be RGBA ( 0.1 , 0.2 , 0.3, 0.4 )

aColors = CAVObj.Elements.Array

aColors(0,47) = 0.1

aColors(1,47) = 0.2

aColors(2,47) = 0.3

aColors(3,47) = 0.4

CAVObj.Elements.Array = aColors

' Retrieve the color and print it

aColors = CAVObj.Elements.Array

Application.LogMessage "Color 47 is (" & aColors(0,47) & ", " & aColors(1,47) & ", " & aColors(2,47) & ", " & aColors(3,47) & ")" 

' Now switch to short datatype and print it

chgOp.Parameters("desireddatatype").Value = 0		' == SetValue chgOp & ".desireddatatype", 0

Application.LogMessage "CAV last datatype = " & dtype.Value

' Retrieve the color and print it

aColors = CAVObj.Elements.Array

Application.LogMessage "Color 47 is (" & aColors(0,47) & ", " & aColors(1,47) & ", " & aColors(2,47) & ", " & aColors(3,47) & ")" 

'Output

' INFO : CAV datatype = 0

' INFO : CAV new datatype = 1

' INFO : Color 47 is (0.100000001490116, 0.200000002980232, 0.300000011920929, 0.400000005960464)

' INFO : CAV last datatype = 0

' INFO : Color 47 is (9.80392172932625E-02, 0.200000002980232, 0.298039227724075, 0.400000005960464)