Material Messages

Action Messages

• APPEARANCE_PARAMETER_CHANGE - Changes a material parameter, given the node ID, the parameter name, and the new data to set. This message is undoable and broadcastable. This default maximum wait time for this message is 50.

  Parameters:

  • targetIds (tuple) - A tuple of node IDs.

  • parameterCategory (int) - The category of the parameter: 0 - unknown; 1 - object; 2 - material; 3 - lighting.

  • parameterName (unicode) - The name of the parameter. (See "Class ParameterConstant" in the Showcase API Reference documentation.)

  • parameterData (unicode) - The parameter data in string format.

  • forceCreation (bool) - If True, and the parameter doesn't exist, the parameter is created using the format specified in the following argument.

  • createdType (int) - If parameter creation was forced, use this type: 0 - String; 1 - Double; 2 - Array of 2 doubles; 3 - Array of 3 doubles; 4 - Array of 4 doubles; 5 - AffineMatrix; 6 - File. (See 'enum Type' under "awSupport:Parameter" in the Showcase API Reference documentation.)

• APPEARANCE_PARAMETERS_CHANGE - As APPEARANCE_PARAMETER_CHANGE, but take a tuple for each of the non-target parameters and set them all appropriatelly. All the parameter tuples should be the same length. This message is undoable and broadcastable.

  Parameters:

  • targetIds (tuple) - A tuple of node IDs.

  • parameterCategories (tuple) - The category of the parameter: 0 - unknown; 1 - object; 2 - material; 3 - lighting.

  • parameterNames (tuple) - The name of the parameter. (See "Class ParameterConstant" in the Showcase API Reference documentation.)

  • parameterData (tuple) - The parameter data in string format.

  • forceCreations (tuple) - If True, and the parameter doesn't exist, the parameter is created using the format specified in the following argument.

  • createdTypes (tuple) - If parameter creation was forced, use this type: 0 - String; 1 - Double; 2 - Array of 2 doubles; 3 - Array of 3 doubles; 4 - Array of 4 doubles; 5 - AffineMatrix; 6 - File. (See 'enum Type' under "awSupport:Parameter" in the Showcase API Reference documentation.)

• ASSIGN_EXISTING_MATERIAL - Assigns the material of the given name to the given list of targets. If the target is empty, then the material is assigned to the currently selected objects. This message is undoable and broadcastable. This message will trigger the following response messages: MATERIAL_ASSIGNMENT_CHANGED. This default maximum wait time for this message is 10.

  Parameters:

  • materialName (unicode) - The name of existing material to assign.

  • targets (tuple) - The IDs of the objects to assign the material to.

• ASSIGN_LIBRARY_MATERIAL - Assigns the library material of the given name to the given list of targets. If the target is empty, the material is assigned to the currently selected objects. This message is undoable and broadcastable. This message will trigger the following response messages: MATERIAL_ASSIGNMENT_CHANGED. This default maximum wait time for this message is 10.

  Parameters:

  • materialName (unicode) - The names of existing material to assign.

  • targets (tuple) - The IDs of the objects to assign the material to.

• COPY_MATERIAL - Adds the material on the given target to the copy buffer. If no target is specified, copies the material from the currently selected target. Works only if one target is given, or one target is currently selected. This message is broadcastable.

  Parameters:

  • targets (tuple) - The IDs of the objects to copy material from.

• MATERIAL_CHANGE_PARAMETER - Changes a parameter on one or more materials. This message is undoable and broadcastable.

  Parameters:

  • materialIds (tuple) - The IDs of the materials.

  • parameterName (unicode) - The name of the new parameter.

  • parameterType (int) - The type of the new parameter.

  • parameterValue (unicode) - The value of the new parameter as a string.

  • forceCreation (bool) - If True, and the parameter doesn't exist, create it using the type specified in the following argument.

  • modifyLinked (bool) - True to cause all parameters linked to this one to be modified.

• MATERIAL_COMPUTE_OCCLUSION - Starts computation of ambient occlusion (shadows). This message will trigger the following response messages: MATERIAL_OCCLUSION_RECOMPILE_FINISHED. This default maximum wait time for this message is 300.

  Parameters:

  • tuple of receiver ids (tuple) - A tuple of IDs corresponding to nodes that will receive ambient shadows as a result of computation.

  • rays per sample (int) - The number of occlusion rays per sample point to cast.

  • resolution factor (float) - A factor that influences the number of pixels in the occlusion texture map.

  • shadow spread (float) - Aperture angle used to generate occlusion rays.

  • use drop-off (bool) - True to compute closest distances, False to just test for object hits.

  • drop-off distance (float) - A distance used to discard rays that intersect far away objects.

  • drop-off rate (float) - Rate of decay in the contribution of a ray based on its closest intersection distance.

  • chord length parameterization (bool) - True to sample uniformly in object space, False to sample in UV-parameterization.

  • ambient shadow correction (float) - A factor used to correct ambient shadows by offsetting the ray's origin.

  • filter diameter (int) - The diameter, in pixels, of the blur filter applied to occlusion textures.

  • minimum tile size (int) - The minimum allowed size, in pixels, of a surface's occlusion sub-texture.

  • use environment floor (bool) - True to include the environment floor in the computation.

• MATERIAL_CREATE - Internal message. Creates a scene material given its XML representation. This message is undoable and broadcastable.

  Parameters:

  • material (ata.Da) - The XML representation of the material to be created and added to the scene.

• MATERIAL_DELETE - Deletes the scene material with the given name. This message is undoable and broadcastable. This message will trigger the following response messages: MATERIAL_DELETED. This default maximum wait time for this message is 50.

  Parameters:

  • materialName (unicode) - The name of the scene material to be deleted.

• MATERIAL_DELETE_ALL_LAYERS - Removes all layer materials from the given target nodes. This message is undoable and broadcastable.

  Parameters:

  • targetIds (tuple) - The ids of the nodes whose layer materials will be removed.

• MATERIAL_DELETE_AS_LAYER - Internal message. Deletes the material with the given ID as a layer from the target nodes. This message is undoable and broadcastable.

  Parameters:

  • materialId (unicode) - The ID of the material to be deleted.

  • targetIds (tuple) - The IDs of the target nodes.

• MATERIAL_DELETE_UNUSED - Deletes the unused materials in the document. This message is undoable and broadcastable.

• MATERIAL_DUPLICATE - Duplicates the material with the given name and adds it to the scene. This message is undoable and broadcastable.

  Parameters:

  • materialName (unicode) - The name of the material to duplicate.

  • isSceneMaterial (bool) - True if the material is a scene material, False if it is a library material.

• MATERIAL_ENABLE_SWATCH_GENERATION - Enables/disables the generation of the material swatches.

  Parameters:

  • enable (bool) - True to enable swatch generation, False to disable swatch generation.

• MATERIAL_ENABLE_UI_UPDATE - Turns on/of updating of the material UI List.

  Parameters:

  • enableUpdate (bool) - True if UI list should be updatable, False if not.

• MATERIAL_GROUP_CREATE - Creates an empty material file on disk and loads it into showcase as a material category. This message is undoable and broadcastable.

  Parameters:

  • path (unicode) - The directory where the materialfile is created.

  • filename (unicode) - The full name of the materialfile.

  • label (unicode) - The label shown in the UI

• MATERIAL_GROUP_DELETE - Unloads the specified category in showcase and deletes the corresponding materialfile on disk. This operation is NOT undoable.

  Parameters:

  • path (unicode) - The directory containing the materialfile.

  • filename (unicode) - The full name of the materialfile.

• MATERIAL_GROUP_RENAME - Renames the specified material group. This message is undoable and broadcastable.

  Parameters:

  • groupName (unicode) - The name of the material group, , compound of library id and group id.

  • newName (unicode) - The new name of the material group.

• MATERIAL_INSERT_AS_LAYER - Internal message. Inserts the material with the given ID as a layer at the given index for the target nodes. This message is undoable and broadcastable.

  Parameters:

  • materialId (unicode) - The ID of the material to be inserted.

  • targetIds (tuple) - The IDs of the target nodes.

  • isSceneMaterial (bool) - True if the material is a scene material, False if it is a library material.

  • index (int) - The index of the layer at which the material should be inserted. If -1, the material is appended.

• MATERIAL_LIBRARY_RENAME - Renames the specified material library. This message is undoable and broadcastable.

  Parameters:

  • libraryId (unicode) - The id of the material library.

  • newName (unicode) - The new name of the library.

• MATERIAL_LOAD_LIBRARY_PATHS - Loads the materials from the given files into the library. This default maximum wait time for this message is 50.

  Parameters:

  • materialFilePaths (tuple) - A tuple consisting of the material files to load.

• MATERIAL_MOVE_LAYER - Rearrange layer materials. This message is undoable and broadcastable.

  Parameters:

  • targetIds (tuple) - The layers, specified as a tuple of (materialId, nodeId) pairs.

  • index (int) - The new index of the material.

  • absolute (bool) - True if the new index is absolute, False if it is a relative offset.

• MATERIAL_RENAME - Renames the specified scene material. If the material does not exist, the operation does nothing. This message is undoable and broadcastable.

  Parameters:

  • materialId (unicode) - The id of the material in the scene.

  • newName (unicode) - The new name of the material.

• MATERIAL_REPLACE_LAYER - Replace a layer material with a different material. This message is undoable and broadcastable.

  Parameters:

  • targetIds (tuple) - The layers, specified as a tuple of (materialId, nodeId) pairs.

  • newMaterialId (unicode) - The id of the new material.

• MATERIAL_SET_SELECTION_STYLE - Changes the selection drawing style or color. This message will trigger the following response messages: MATERIAL_SELECTION_STYLE_CHANGED. This default maximum wait time for this message is 10.

  Parameters:

  • drawStyle (unicode) - The requested selection draw style: 'AnimatedGrid', 'WhiteWireframe', 'BlueWireframe', 'BlackWireframe'. (See "Class SelectionDrawStyleMode" in the Showcase API Reference documentation.)

• MATERIAL_SNAP_SWATCH - Generates the material swatch for the specified material using the given image filename and dimensions.

  Parameters:

  • materialName (unicode) - The name of the material to use.

  • imageFilename (unicode) - The filename for the generated image.

  • width (int) - The width of the swatch image.

  • height (int) - The height of the swatch image.

  • synchronous (bool) - True if the swatch should be snapped immediately. False if the snap is queued.

• MATERIAL_SWATCH_GENERATION_UI - Adds/removes a UI Id on the list of UI:s needing material swatch generation. If no UI:s are in this list swatch generation will be turned off. The Id's used today

  Parameters:

  • uiName (unicode) - The Id of the UI needing swatch generation.

  • enableGeneration (bool) - True if UI should be added, False if it should be removed.

• MATERIAL_UI_SET_MODE - Shows or hides the Material Library user interface.

  Parameters:

  • visible (bool) - True to show, False to hide.

• MATERIAL_UI_SWATCHES_UPDATE - Refreshes the scene material swatches regarding to the current environment.

• MATERIAL_UNLOAD_LIBRARY_PATHS - Unloads the materials from the given files from the library. This default maximum wait time for this message is 20.

  Parameters:

  • materialFilePaths (tuple) - A tuple consisting of the material files to unload.

• PASTE_MATERIAL - Assigns the most recently copied material to the given targets. If no targets are specified, works on the current selection. This message is undoable and broadcastable. This message will trigger the following response messages: MATERIAL_ASSIGNMENT_CHANGED. This default maximum wait time for this message is 10.

  Parameters:

  • targets (tuple) - The IDs of the objects to assign the material to.

Information Messages

• APPEARANCE_PARAMETER_CHANGED - Indicates that a material parameter was changed.

  Parameters:

  • targetIds (tuple) - A tuple of node IDs that were affected.

  • parameterCategory (int) - The category of the modified parameter: 0 - unknown; 1 - object; 2 - material; 3 - lighting.

  • parameterName (unicode) - The name of the parameter that was changed.

  • parameterData (unicode) - The new value for this parameter.

• MATERIAL_COPIED - Indicates that a material has been copied onto the clipboard.

  Parameters:

  • Name (unicode) - The name of the material that was copied onto the clipboard.

• MATERIAL_CREATED - Indicates that a material has been created and added to the scene.

  Parameters:

  • materialName (unicode) - The name of the scene material that was created.

• MATERIAL_DUPLICATED - Indicates that the material was duplicated and added to the scene.

  Parameters:

  • originalName (unicode) - The name of the material that was duplicated.

  • duplicateName (unicode) - The name of the duplicate.

• MATERIAL_LAYER_REPLACED - Indicates that a layer material has been replaced with a different material.

  Parameters:

  • targetIds (tuple) - The layers, specified as a tuple of (oldMaterialId, nodeId) pairs.

  • newMaterialId (unicode) - The id of the new material that replaced the old ones.

• MATERIAL_LIST - Lists the materials currently in the library.

  Parameters:

  • materials (list) - The names of the materials in the library.

• MATERIAL_RENAMED - Indicates that the MATERIAL_RENAME operation completed successfully. This message is undoable and broadcastable.

  Parameters:

  • materialId (unicode) - The id of the material in the scene.

  • newName (unicode) - The new name of the material.

• MATERIAL_SWATCH_SNAPPED - Indicates that a material swatch image has just been generated.

  Parameters:

  • material (unicode) - The name of the material used in the swatch image.

  • filename (unicode) - The filename of the swatch image.

Response Messages

• MATERIAL_ASSIGNMENT_CHANGED - Indicates that one or more targets' material assignment has changed.

  Parameters:

  • targets (tuple) - The IDs of the objects whose material assignment has changed.

• MATERIAL_DELETED - Indicates that a scene material has been deleted.

  Parameters:

  • materialName (unicode) - The name of the scene material that was deleted.

• MATERIAL_OCCLUSION_COMPUTE_CANCELLED - Indicates that computation of ambient occlusion (shadows) has been cancelled.

• MATERIAL_OCCLUSION_COMPUTE_FINISHED - Indicates that computation of ambient occlusion (shadows) has completed.

• MATERIAL_OCCLUSION_RECOMPILE_FINISHED - Indicates that recompilation of ambient occlusion (shadow) receivers has completed.

• MATERIAL_SELECTION_STYLE_CHANGED - Indicates that the material for selection drawing style or color has changed.

  Parameters:

  • drawStyle (unicode) - The new selection draw style: 'AnimatedGrid', 'WhiteWireframe', 'BlueWireframe', 'BlackWireframe'.