ChangeVertexColor Datatype

Introduced

6.5

Description

Applies a VertexColorChangeDatatype 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.

Scripting Syntax

    ChangeVertexColorDatatype( [InputObj], DesiredDatatype, [OutputObjs] )

Parameters

Parameter | Type | Description
InputObj | VertexColor by name, ClusterProperty or XSICollection | VertexColor property to change Default Value: Currently selected objects are used as the main group.
DesiredDatatype | Integer | Specifies the desired datatype. Possible Values: • 0: short • 1: float (32 bit)
OutputObjs [out] | XSICollection of Operator object(s). | Returns the new Operator in an XSICollection.

Return Value

An XSICollection containing the newly created Operator.

Examples

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)

See Also

ApplyOp | Operator | CreateVertexColorSupport

Autodesk Softimage v7.5