MaterialLibrary Values

A MaterialLibrary contains a table of materials as an array. The 3ds Max system global variables currentMaterialLibrary and sceneMaterials contain MaterialLibrary instances. System global variable meditMaterials strictly speaking is not a MaterialLibrary value, rather it is a virtual array of the materials in the Material Editor sample slots. In most cases, meditMaterials can be considered a MaterialLibrary value, with the exception that you can assign a material or textureMap value to a meditMaterials element. MaterialLibrary values are mappable.

Constructors

currentMaterialLibrary -- system global

sceneMaterials -- system global, the materials in the scene

meditMaterials -- system global, the materials in material editor

 

materialLibrary { <material> }

Creates a temporary material library. You can add materials to this library with the append function, but there is currently no way to save it or make it the current library.

Properties

<mat_lib>.count : Integer, read-only

Returns the number of materials in the library.

Operators

<mat_lib>[ <integer> | <name> | <string> ]

Retrieves a material from the material library. Material libraries can be indexed just like arrays with an integer index, or by using the material name as a Name or String value.

<mat_lib>[ <integer> | <name> | <string> ] = ( <material> | <textureMap> )

Assigns the specified material or textureMap to the material library. Material libraries can be indexed just like arrays with an integer index, or by using the material name as a Name or String value. If the material library is indexed by an index value, and the index value is larger than the size of the material library, a runtime error is generated. If the material library is indexed by a material name, and the material name is not already present in the material library, the material or textureMap is appended to the material library.

meditMaterials[<slot_index_integer>]

Returns the material or textureMap in the indexed material editor slot. Valid <slot_index_integer> values are 1 through 24.

meditMaterials[<slot_index_integer>] = ( <material> | <textureMap> )

Assigns the specified material or textureMap to the indexed material editor slot. Valid <slot_index_integer> values are 1 through 24. For example:

meditMaterials[3]= standard()

Methods

append <mat_lib> <material>

Append the specified material to the material library. This method is not applicable to the meditMaterials material library.

deleteItem <mat_lib> ( <integer> | <name> | <string> )

Delete the specified material from the material library. The material can be specified as the indexed material in the material library, as a String, or as a Name. This method is not applicable to the meditMaterials material library.

findItem <mat_lib> <material>

Returns the index of the material in the material library or zero if the material is not in the material library.

Associated Methods

getMeditMaterial <slot_index_integer>

Returns the top level material or textureMap in the specified material editor slot. Valid <slot_index_integer> values are 1 through 24.

For example:

foo = getMeditMaterial 3

setMeditMaterial <slot_index> ( <material> | <textureMap> )

Complements the getMeditMaterial function allowing you to place a material or textureMap into the numbered material editor slot.

loadDefaultMatLib()

Loads the default 3ds Max material library file.

loadMaterialLibrary <filename_string>

Loads the named 3ds Max material library file, which becomes the current material library. If the file name does not have a fully specified directory path, the function searches through all the currently configured bitmap paths. Returns true if the loads succeeds, false if it fails.

saveMaterialLibrary <filename_string>

Saves the current material library into the named file. Returns true if the save succeeds, false if it fails.

fileOpenMatLib()

This method displays the File Open dialog and allows the user to select a material library to load. Note: If the Material/Map Browser is open when fileOpenMatLib() is called, the Material/Map Browser display is not updated.

fileSaveAsMatLib()

Displays the standard Save File As dialog to allow the user to save the current material library.

fileSaveMatLib [quiet:<bool>]

If the current material library has been saved previously (has been named) this method saves the material library to the same file. Otherwise it displays the standard Save File As dialog to allow the user to save the current material library.

For details on the quiet: option available in 3ds Max 8 and higher, please see Quiet Mode

getMatLibFileName()

Returns the current material library file name as a String value.

Examples

You can use the standard array indexing accessors to get and set materials in the library. MaterialLibraries also allow you to use name and string literals as indexes to get at materials in them by name:

$foo.material = currentMaterialLibrary["Rough Gold"]

for m in sceneMaterials do print m.name

append currentMaterialLibrary $baz.material

<MAXMaterialLibrary>loadTempMaterialLibrary <mtllib_file_name>

new.gif NEW in 3ds Max 9: Loads the named 3ds Max material library file. Unlike loadMaterialLibrary(), the material library does not become the current material library. If the file name does not have a fully specified directory path, the function searches the material library path and through all the currently configured bitmap paths. Returns MAXMaterialLibrary value if the loading succeeded, undefined if it failed.

saveTempMaterialLibrary <MAXMaterialLibrary> <mtllib_file_name>

new.gif NEW in 3ds Max 9: Saves the specified MAXMaterialLibrary value into the named file. Returns true if the save succeeded, false if it failed.

Example:

a = loadTempMaterialLibrary "mrArch_DesignTemplates.mat"

#materialLibrary()

a[1]

brushed metal:Arch___Design__mi

saveTempMaterialLibrary a "$matlibs/test.mat"

true