Softimage 2014

Custom Primitives

A custom primitive object is an implicit primitive, and you can fully define its representation. You can use a custom primitive object like any other primitives in Softimage such as the cones and spheres.

You must first register the custom primitive object using PluginRegistrar.RegisterPrimitive inside the XSILoadPlugin callback. After registering the custom primitive object, it can be created using the create primitive commands like GetPrim and X3DObject::AddPrimitive. You can define parameters for the custom primitive object and tweak where they appear in the property page using the DefineLayout callback. The PPGEvent callback can be used for tracking the parameter changes using the siParameterChange event id. The Draw callback draws the custom primitive object. The custom primitive object is drawn in the scene directly using OpenGL calls. Like other implicit geometry, a custom primitive object can be converted using either the SIConvert command or CreatePrim command. The custom primitive object can only be converted to a PolygonMesh.

The BoundingBox callback returns the bounding box for the custom primitive. The bounding box represents a simplified version of the custom primitive object and is used for improving performance in certain operations. Unlike the Draw callback, the bounding box values are cached internally and only called when there are updates such as changes to parameter values.

You can use the Custom Primitive Wizard to generate the code for a self-installing plug-in that contains a custom primitive object. To access the Custom Primitive Wizard, select Plug-in Manager File New Primitive.

See the custom primitive example in the SDK workgroup about how to define a custom primitive object (<your_installation_folder>\Softimage 2014\XSISDK\examples\workgroup\Addons\CustomPrimitive).

Enhancements to the GridData Object

New methods, attributes, and events are added to enhance the GridData object. The new methods enable you to perform useful functions on the GridData object such as set new column type, insertion and removal of rows and columns, and others.

These are the new attributes: siUIGridLockRowHeight to freeze the row height, siUIGridLockColumnWidth to freeze the column width, and siUIGridThumbnailSize to set the default thumbnail size to use when a size is not specified. The newly added events are: OnBeginValueChange which is called before modifying a parameter, OnEndValueChange which is called after modifying a parameter, OnBeginSelectionChange which is called before applying a selection change to a grid widget, OnEndSelectionChange which is called after a selection change is applied to a grid widget, OnButtonClicked which is called when a button is clicked in a grid widget, OnHeaderDoubleClick which is called when a header is double-clicked in a grid widget, OnContextMenuInit which is called when a mouse is right-clicked over a grid widget, and OnContextMenuSelected which is called when a contextual menu item is selected over a grid widget.

See the GridData example in the SDK workgroup for more information.

Upgraded Python and New Environment Variable

For Windows and Linux, the version that is installed with Softimage is Python v2.7.3. The version of the pywin32 extensions for both Windows and Linux is v217. Additionally, a new WARNPYTHON3K environment variable can be set to 1 to generate a warning in the script log for features that will not work or work differently in Python 3.x.

New Classes (C++)

• CustomPrimitive – Represents a custom primitive object.
• CustomPrimitiveContext – Context object that is returned by the ConvertToGeom() callback for the custom primitive.

New Callbacks (C++)

The following callbacks are added for the custom primitive object:

• Define – Called whenever the custom primitive object is created. You can add parameters to the custom primitive using this callback.
• DefineLayout – Called immediately after the Define callback is called for the first time in a session. You can also call it when you use the PPG.Refresh method. You can define the layout of the user interface (UI) controls in the property page using this callback.
• Draw – Called when there is a request to draw the custom primitive object. The coordinates are set to the local space of the custom primitive object.
• BoundingBox – Called when there is a request for the custom primitive's bounding box.
• ConvertToGeom – Called when the custom primitive object is passed into SIConvert or CreatePrim commands to convert the geometry.
• The PPGEvent is the callback for all the property page events.

New Methods (C++)

• Framebuffer::GetResolvedPath(const CTime &in_rTime, const CRef& in_rCtx) – Takes the output file name path template given in the framebuffer and resolves it for the specified time into a real path name, and returns it as a CString. The in_rTime parameter controls the result of the [Frame] and [Field] tokens.
• Framebuffer::GetResolvedPath(const CRef & in_rCtx) – Takes the output file name path template given in the framebuffer and resolves it into a time-independent path, where any instance of [Frame] is substituted with the a sequence of '#' symbols, which represent the current frame number and padding width.
• CICEAttributeDataArray::SetData() – Accessor to the encapsulated array for writing to the data array.
• CICEAttributeDataArray::SetArray() and CICEAttributeDataArray<bool>::SetArray() – To set the values in the array.
• CICEAttributeDataArrayCustomType::SetArray(const TData** in_ppData, ULONG in_count, ULONG in_fixedElemSize) and CICEAttributeDataArrayCustomType::SetArray(const TData** in_ppData, ULONG in_count, ULONG* in_pElementSizes) – To set the values in the custom-typed data array.
• CICEAttributeDataArrayString::SetArray() – To set all the values in the string ICE attribute.
• CICEAttributeDataArray2D::SetSubArray() and CICEAttributeDataArray2DString::SetSubArray() – To set the sub-array at a given index. This is only supported for writable attributes and not available for built-in attributes.
• CICEAttributeDataArray2D::SetArray2D() – To set all the values in the 2D ICE attribute.
• CICEAttributeDataArray2DCustomType::SetSubArray(ULONG in_index, const unsigned char** in_ppData, ULONG in_count, ULONG* in_pElemSizes) and CICEAttributeDataArray2DCustomType::SetSubArray (ULONG in_index, const unsigned char** in_ppData, ULONG in_count, ULONG in_fixedElemSize) – To set the sub-array at a given index. This is only supported for writable attributes and not available for built-in attributes.
• CShape::SetAsInstance() – To set as a shape instance.
• CShape::SetAsReference() – To set as a shape reference.
• CShape::SetAsTrivial() – To set as a trivial shape type.
• CValue::CValue(const CStringArray& valSrc) – Constructor.
• CValue::CValue& operator=(const CStringArray& valSrc ) – Assignment.
• CValue::operator CStringArray&() – CStringArray extractor.
• CValue::operator == (const CStringArray&) const [inline] – CStringArray equality operator.
• CustomPrimitive::AddParameter() – Adds a new parameter to a custom primitive object.
• CustomPrimitive::RemoveParameter() – Removes the specified parameter from a custom primitive object.
• PluginRegistrar::RegisterPrimitive() – Registers a custom primitive type.
• GridData::SetIntColumnDef() – Changes a column's type to siColumnInt.
• GridData::GetIntColumnDef() – Retrieves siColumnInt definition for a column.
• GridData::SetFloatColumnDef() – Changes a column's type to siColumnFloat.
• GridData::GetFloatColumnDef() – Retrieves siColumnFloat definition for a column.
• GridData::SetVectorColumnDef() – Changes a column's type to siColumnVector.
• GridData::GetVectorColumnDef() – Retrieves siColumnVector definition for a column.
• GridData::SetFileColumnDef() – Changes a column's type to siColumnFile.
• GridData::GetFileColumnDef() – Retrieves siColumnFile definition for a column.
• GridData::SetShaderBallColumnDef() – Changes a column's type to siColumnShaderBall.
• GridData::GetShaderBallColumnDef() – Retrieves siColumnShaderBall definition for a column.
• GridData::SetImageClipColumnDef() – Changes a column's type to siColumnImageClip.
• GridData::GetImageClipColumnDef() – Retrieves siColumnImageClip definition for a column.
• GridData::InsertRow() – Inserts a new row.
• GridData::RemoveRow() – Removes a row.
• GridData::InsertColumn() – Inserts a new column.
• GridData::RemoveColumn() – Removes a column.
• GridData::SetCellBackgroundColor() – Changes the background color of a cell.
• GridData::GetCellBackgroundColor() – Retrieves the background color of a cell.
• GridData::SetColumnsVisibility() – Changes the visibility of the columns.
• GridData::SetRowsVisibility() – Changes the visibility of the rows.
• GridData::SetCellReadOnlyFlags() – Sets the read-only flags for the cells.
• GridData::GetCellReadOnlyFlags() – Retrieves the read-only flags for the cells.
• GridData::PutMultiSelectionMode() – Sets the multi-selection mode.
• GridData::GetMultiSelectionMode() – Retrieves the multi selection mode.
• GridData::PutReadOnly() – Sets the read-only mode for the whole grid data.
• GridData::GetReadOnly() – Retrieves the current read-only mode for the whole grid data.
• CParameterRefArray::PlotAnimation(double in_startFrame, double in_stopFrame, double in_stepFrame, bool in_bProcessRotation, bool in_bDisplayProgressBar, CLongArray &out_startParamValuesIndicesArray, CDoubleArray &out_plottedFramesArray, CDoubleArray &out_plottedValuesArray) – Returns an array of plotted values obtained by plotting the parameter values from consecutive frames in an animation.
• CParameterRefArray::PlotAnimation(double in_startFrame, double in_stepFrame, const CDoubleArray &in_frameset, double in_frameRate, siFCurveType in_fcurveTypeToPlot, siFCurveInterpolation in_interpolation, bool in_bFitValues, double in_fitTolerance, bool in_bProcessRotation, bool in_bDisplayProgressBar) – Creates and returns an array of FCurve objects by plotting the parameter values from consecutive frames in an animation. The resulting FCurve objects are transients and are not connected to any components. All resulting FCurve objects are parented to the Application object.
• Scene::GetRenderableCameras() – Returns an array of all cameras in the scene and additional cameras that can be rendered.
• Scene::GetAllCacheClipsAndObjects() – Returns an array of all the file cache clips in the scene as well as a list of the object names that they are applied on.

New Methods (Object Model)

• GridData.SetColumnDef – Sets a column definition.
• GridData.GetColumnDef – Gets a column definition.
• GridData.InsertColumn – Inserts a new column at a specified index. The new column type is siColumnStandard. This can be changed later by calling the SetColumnType or SetColumnDef methods. The existing columns are shifted to the right to accommodate the new column.
• GridData.InsertRow – Inserts a row at a specified index. The existing rows are shifted down to accommodate the new row.
• GridData.RemoveColumn – Removes the column at a specified index. The columns to the right of the removed column are shifted to the left by one index.
• GridData.RemoveRow – Removes the row at a specified index. The rows under the removed row are shifted up by one index.
• GridData.SetColumnsVisibility – Hides or shows a set of columns.
• GridData.SetRowsVisibility – Hides or shows a set of rows.
• GridData.SetCellReadOnlyFlags – Changes the read-only flag of the specified cells.
• GridData.GetCellReadOnlyFlags – Gets the read-only flag of the specified cells.
• GridData.SetCellBackgroundColor – Sets the background color of a cell.
• GridData.GetCellBackgroundColor – Gets the background color of a specified cell.
• GridWidget.GetSelection – Gets the current selection.

New Structures (C++)

• CShape::ParameterInstance – A struct to hold the parameters for a shape instance.
• CShape::ParameterReference – A struct to hold the parameters for a shape reference.

New Commands

• AddShotClip – Creates a new clip and adds it to the track. A clip represents the time at which a particular camera is active.
• GetShotClip – Finds a clip given the sequence time in frames.
• DeleteUnusedCameraSequencerTracks – Deletes all tracks in the camera sequencer that are currently not in use (have no clips on them).
• FreezeLipSync – Deletes existing lip sync operator and generates FCurves on shape tracks.
• GenerateLipSync – Generates lip-sync animation for an evolver character.
• RemoveICESimInitState – Removes the initial state from a simulation.
• PlotFrameSetToActions – Creates and returns new actions by plotting values from a frame set consisting of frame numbers.
• DeleteUnusedCameraSequencerTracks – Deletes all the tracks in the camera sequencer that are currently not in use.
• CreateShotCameraAndSwitch – Creates a shot camera based on a source viewport and sets the shot camera as the camera for another viewport.
• CreateShotCamera – Creates a shot camera based on a source camera.
• GetPrimCameraWithoutInterest – Creates a camera primitive object without an interest.
• PlotCamSeqToActions – Creates and returns new actions by plotting values from the consecutive camera sequencer frames.
• PlotCamSeqShape – Plots objects with shape animations in the camera sequencer. A shape source (key) is created for each plotted frame of shape animation.
• PlotCamSeqForCachedObjects – Plots the file cached objects to the new cache files in the camera sequencer time.
• ApplyCamSeqFileCacheSources – Deletes the supplied clips and sequentially applies each file cache location to an input object as a cache clip.
• GetSceneFrameSetFromCamSeq – Gets the time remapped frame numbers in scene time from a frame range in the camera sequencer.
• PlotSequencerCamera – Creates a single camera for all shot clips in the camera sequencer. Also, creates a new action by plotting values from the consecutive sequence frames of camera animation.

New Properties (Object Model)

• GridData.MultiSelectionMode – Sets the selection mode for the grid data.
• GridData.ReadOnly – Sets the read only mode for the whole grid data.
• Scene.RenderableCameras – Returns an SIObjectCollection containing all the camera objects that can be used by mental ray and other renderers.

New Enumerations

• siICERBDType_Bbox, siICERBDType_ConvexHull, and siICERBDType_ExactShape – The constants that define the type used in rigid body dynamics.
• siRenderNoAttributes – For not displaying the mesh attributes, such as vertices, edges, and others.
• siOverrideSource – Override source.
• siClipShotType – The constant string that represents the shot clips.
• siTrackShotType – The constant string that represents the shot track.
• siGridDataMultiselectionMode

  Constant	Description
  siCellSelection	One cell at a time is selected.
  siColumnSelection	Selection is restrained to a single column.
  siGlobalSelection	No restriction on multi-selection (default).

• siGridWidgetColumnType

  Constant	Description
  siColumnInt	The value of the cell is an integer number.
  siColumnFloat	The value of the cell is a floating point number.
  siColumnImageClip	The value of the cell is an image clip that is represented by a thumbnail.
  siColumnColor	The value of the cell is a color.
  siColumnVector	The value of the cell is an array of doubles of dimension 2, 3, or 4 depending on the column definition.
  siColumnButton	The value of the cell is a button label that is represented by a button.
  siColumnFile	The value of the cell is a file or folder name.
  siColumnshaderBall	The value of the cell is a material that is represented by a shader ball.
  siColumnMultiLine	A column of text that can span over multiple lines.

• siPPGEventID

  Constant	Description
  siGridDataEvent	A GridData event. Depending on the event, the following callbacks are invoked: _OnBeginValueChange and _OnEndValueChange _OnBeginSelectionChange and _OnEndSelectionChange _OnButtonClicked _OnHeaderDoubleClick _OnContextMenuInit and _OnContextMenuSelected

• siDragAndDropAction2 – Following are the possible actions for the siOnDragAndDrop2 event.

  Constant	Description
  siDragOverAction	Drag over. The source object is dragged over a supported target view such as scene explorer or viewport.
  siDropAction	Drop. The source object is dropped into a supported target view such as scene explorer or viewport.
  siDragEnterAction	Drag enter. The source object enters a supported target view such as scene explorer or viewport.
  siDragLeaveAction	Drag leave. The source object leaves a supported target view such as scene explorer or viewport.

• siDragAndDropModifiers – Following are the possible mouse and keyboard modifiers for the siOnDragAndDrop2 event.

  Constant	Description
  siDragModifierLButton	The left mouse button is down.
  siDragModifierRButton	The right mouse button is down.
  siDragModifierShift	The shift key is down.
  siDragModifierCtrl	The control key is down.
  siDragModifierMButton	The middle mouse button is down.
  siDragModifierAlt	The alt key is down.

• siDropEffect – Following are the possible mouse icons when a drag operation is accepted by the siOnDragAndDrop2 event.

  Constant	Description
  siDropEffectCopy	Copy. The mouse icon shows a rectangle and a plus sign (+) under the standard icon.
  siDropEffectMove	Move. The mouse icon shows a rectangle under the standard icon.
  siDropEffectLink	Link. The mouse icon shows a rectangle and a link sign (arrow) under the standard icon.

• siRenderQueryType::siRenderQueryHasPreMulAlphaOutput – Returns a boolean indicating whether the fragments returned from the renderer is pre-multiplied with alpha. This is used for color correction in the preview windows.
• siPPGItemAttribute::siUITabSize – A numeric attribute that applies to siControlTextEditor. Specifies the size of the tabs in the text editor control.
• siPPGItemAttribute::siUIUseSpacesForTab – A boolean attribute that applies to siControlTextEditor. Inserts space characters instead of a tab character when pressing the tab key when true.
• siPPGItemAttribute::siUIShowIndentationGuides – A boolean attribute that applies to siControlTextEditor. Displays the indentation guides that appear as dotted vertical lines within the indentation white space for each tab size columns.
• siPPGItemAttribute::siUIShowWhitespace – A boolean attribute that applies to siControlTextEditor. Displays whitespace characters (spaces and tabs) in the text editor control. Space characters appear as small centered dots and tab characters as light arrows pointing to the right.

New PPGEvent Types (C++)

• siGridDataOnBeginValueChange
• siGridDataOnEndValueChange
• siGridDataOnBeginSelectionChange
• siGridDataOnEndSelectionChange
• siGridDataOnButtonClicked
• siGridDataOnHeaderDoubleClick
• siGridDataOnContextMenuInit
• siGridDataOnContextMenuSelected

New Events

• siOnBeginRenderPass – Fired before a pass gets rendered. This callback can be used to modify the scene before the rendering starts.
• siOnEndRenderPass – Fired after a pass is rendered.
• siOnDragAndDrop2 – Fired when a source enters, leaves, is dragged over or is dropped into a supported view such as scene explorer or viewport. Following are the context attributes:

  Attribute	Description
  DragAndDropAction	A siDragAndDropAction2 value for specifying the type of action that the callback needs to process. Following are the possible actions: siDragOverAction siDropAction siDragEnterAction siDragLeaveAction
  DragSourceObjects	The array of source objects that is being dragged. It can be an array of Softimage SDK objects or strings.
  DragTargetObjects	The array of targets over which the source is being dragged.
  DragTargetView	The view in which the drag and drop operation occurs.
  DragMouseCoordinates	The array (two elements) representing the mouse coordinates (X,Y) in the view client space.
  Drag3DCoordinates	The array (three elements) representing the 3D coordinates (X, Y, and Z) with respect to the mouse position. It is only valid when the DragTargetView attribute is a viewport.
  DragModifiers	The siDragModifiers flag for specifying the combination of modifiers that is currently applied. Following are the possible modifiers: siDragModifierLButton siDragModifierRButton siDragModifierShift siDragModifierCtrl siDragModifierMButton siDragModifierAlt
  DragSourceSupported	Output argument. When the DragAndDropAction attribute is equal to siDragOverAction, the callback must set this output attribute to true, if the source is supported. The default value for this attribute is false. If true is returned, Softimage launches a siOnDragAndDrop2 event when the source is dropped (with a DragAndDropAction equal to siDropAction). If false is returned, Softimage determines whether the siDropAction is called or not. Returning false has the same effect as if the siDragAndDrop2 event is not connected. It is only possible to add support for a new source/target combination with this attribute. The event callback code must return a consistent value for this attribute. If a source/target pair yields a true DragSourceSupported attribute for a siOnDragOverAction call, it must also return true for the siDropAction call.
  DragDropEffect	Output argument. When the DragSourceSupported attribute is true, the siDropEffect attribute controls the icon used for the mouse pointer. Following are the possible values: siDropEffectCopy siDropEffectMove siDropEffectLink

See the Python example in <yourinstallationdirectory>Addons\DragAndDrop\Application\Plugins\DnDEventExample.py for more information.

New View Attributes

• Text Based Editor (Scintilla) Attributes:

  Attribute Name	Description
  showindentationguides	Controls whether the indentation guides are displayed in the editor. Indentation guides appear as dotted vertical lines within the indentation white space for each tab size columns.
  smarthighlighting	Controls whether the editor is highlighting all instances of the currently selected word.

• Fx Tree Attributes:

  Attribute Name	Description
  Targetcontent	Returns or sets the Fx Tree displayed in the view. If more than one item is specified, only the first valid FX Tree is displayed.
  Selectednodes	Returns or sets the selected FX Tree nodes as a comma delimited string containing the full name of the Fx Tree nodes. If nothing is selected, it returns an empty string.

Miscellaneous

The operator preset information such as, Fx operator presets, generator operator presets, and others are removed from the Commands and Scripting Reference section of the SDK help. For information about the operator parameters, refer to the Properties Reference section in the Softimage User's Guide.