Rhino C++ API  6.29
Public Member Functions | Static Public Member Functions | Public Attributes | Friends | List of all members
CRhinoMaterialTable Class Reference

#include <rhinoSdkMaterial.h>

Inheritance diagram for CRhinoMaterialTable:
ON_SimpleArray< CRhinoMaterial * >

Public Member Functions

int AddCopyOfDefaultMaterial ()
 
int AddMaterial (const ON_Material &, bool=FALSE)
 
int CreateMaterial (const ON_Material &material, unsigned int worksession_ref_model_sn, unsigned int linked_idef_sn)
 
ON_UUID CurrentMaterialId () const
 
int CurrentMaterialIndex () const
 
ON::object_material_source CurrentMaterialSource () const
 
bool DeleteMaterial (int)
 
CRhinoDocDocument () const
 
int FindMaterial (const ON_Material &, bool bIgnoreDeleted=true) const
 
int FindMaterial (const wchar_t *material_name, bool bIgnoreDeleted=true) const
 
int FindMaterial (ON_UUID material_id, bool bIgnoreDeleted=true) const
 
void GetMaterials (const ON_MaterialRef *material_ref, const CRhinoMaterial *&front_material, const CRhinoMaterial *&back_material) const
 
void GetMaterials (const ON_UUID &plugin_id, const ON_3dmObjectAttributes &object_attributes, const CRhinoMaterial *&front_material, const CRhinoMaterial *&back_material) const
 
void GetMaterials (const ON_UUID &plugin_id, const ON_Layer &layer, const CRhinoMaterial *&front_material, const CRhinoMaterial *&back_material) const
 
void GetMaterials (const ON_UUID &plugin_id, const ON_RenderingAttributes &rendering_attributes, const CRhinoMaterial *&front_material, const CRhinoMaterial *&back_material) const
 
void GetSortedList (ON_SimpleArray< const CRhinoMaterial * > &sorted_list, bool bIgnoreDeleted, bool bIgnoreReference) const
 
bool InMaterialTable (const ON_Material *material) const
 
bool IsValidMaterialTableIndex (int material_index) const
 
void ListTable (ON_TextLog &text_log, unsigned int level_of_detail) const
 
const CRhinoMaterialMaterial (const ON_ComponentManifestItem &item) const
 
int MaterialCount () const
 
bool ModifyMaterial (const ON_Material &material, int material_index, bool bQuiet=false)
 
const CRhinoMaterialoperator[] (int material_index) const
 
bool ResetMaterial (int material_index)
 
bool SetCurrentMaterialIndex (int material_index, bool bQuiet=FALSE)
 
bool SetCurrentMaterialSource (ON::object_material_source current_material_source)
 
void SetRemapIndex (int, int)
 
void Sort (int(*compare)(const CRhinoMaterial *, const CRhinoMaterial *, void *), int(*cull)(const CRhinoMaterial *, void *), void *p=0)
 
const CRhinoDocTableReferenceTableReference () const
 
bool UndeleteMaterial (int material_index)
 
bool UndoModifyMaterial (int material_index, unsigned int ur_sn=0)
 
bool UndoModifyMaterial (int)
 

Static Public Member Functions

static const CRhinoMaterialWorstPossibleMaterial ()
 

Public Attributes

const CRhinoMaterialDefaultLockedMaterial
 default material for locked objects. More...
 
const CRhinoMaterialDefaultMaterial
 default material for unlocked objects. More...
 

Friends

class CRhinoDoc
 

Member Function Documentation

◆ AddCopyOfDefaultMaterial()

int CRhinoMaterialTable::AddCopyOfDefaultMaterial ( )

Description: Adds a copy of "DefaultMaterial" to the material table. Typically this gets modified a little later. Returns: index of material

◆ AddMaterial()

int CRhinoMaterialTable::AddMaterial ( const ON_Material ,
bool  = FALSE 
)

Description: Adds a new material to the material table.

Parameters: material - [in] definition of new material. The information in material is copied. It is fine to have empty material names

bReference - [in] TRUE if this material is a reference material. Reference materials are not saved in files.

Returns: @untitled table >=0 index of new material -1 material not added because a material with that name already exists.

Remarks: In some cases, calling AddMaterial() can cause the memory references returned by operator[] and CurrentMaterial() to become invalid.

◆ CreateMaterial()

int CRhinoMaterialTable::CreateMaterial ( const ON_Material material,
unsigned int  worksession_ref_model_sn,
unsigned int  linked_idef_sn 
)

Description: Adds a new material to the material table.

Parameters: material - [in] definition of new material. The information in material is copied. It is fine to have empty material names

worksession_ref_model_sn - [in] 0: material is not a reference layer 1: material is a reference linetype but not part of a worksession reference file 2-1000: reserved for future use >1000: worksession reference file serial number

linked_idef_sn - [in] 0: material is not from a liked instance definition 1-1000: reserved for future use >1000: material instance defintion serial number

Returns: @untitled table >=0 index of new material -1 material not added because a material with that name already exists.

Remarks: In some cases, calling AddMaterial() can cause the memory references returned by operator[] and CurrentMaterial() to become invalid.

◆ CurrentMaterialId()

ON_UUID CRhinoMaterialTable::CurrentMaterialId ( ) const

◆ CurrentMaterialIndex()

int CRhinoMaterialTable::CurrentMaterialIndex ( ) const

Description: At all times, there is a "current" material. Unless otherwise specified, new objects are assigned to the current layer. The current layer is never locked, hidden, or deleted.

Returns: Zero based material table index of the current material.

◆ CurrentMaterialSource()

ON::object_material_source CRhinoMaterialTable::CurrentMaterialSource ( ) const

◆ DeleteMaterial()

bool CRhinoMaterialTable::DeleteMaterial ( int  )

Description: Deletes material

Parameters: material_index - [in] zero based index of material to delete. This must be in the range 0 <= material_index < MaterialCount(). bQuiet - [in] If TRUE, no warning message box appears if a material the material cannot be deleted because it is the current material or it contains active geometry.

Returns: TRUE if successful. FALSE if material_index is out of range or the the material cannot be deleted because it is the current material or because it material contains active geometry.

◆ Document()

CRhinoDoc& CRhinoMaterialTable::Document ( ) const

Description: Material tables store the list of materials in a Rhino document.

Returns: CRhinoDocument that owns this material table.

◆ FindMaterial() [1/3]

int CRhinoMaterialTable::FindMaterial ( const ON_Material ,
bool  bIgnoreDeleted = true 
) const

◆ FindMaterial() [2/3]

int CRhinoMaterialTable::FindMaterial ( const wchar_t *  material_name,
bool  bIgnoreDeleted = true 
) const

Remarks: For duplicate materials with the same name, the first material match in the table will be returned. This function will not work for finding unnamed materials.

◆ FindMaterial() [3/3]

int CRhinoMaterialTable::FindMaterial ( ON_UUID  material_id,
bool  bIgnoreDeleted = true 
) const

◆ GetMaterials() [1/4]

void CRhinoMaterialTable::GetMaterials ( const ON_MaterialRef material_ref,
const CRhinoMaterial *&  front_material,
const CRhinoMaterial *&  back_material 
) const

◆ GetMaterials() [2/4]

void CRhinoMaterialTable::GetMaterials ( const ON_UUID plugin_id,
const ON_3dmObjectAttributes object_attributes,
const CRhinoMaterial *&  front_material,
const CRhinoMaterial *&  back_material 
) const

◆ GetMaterials() [3/4]

void CRhinoMaterialTable::GetMaterials ( const ON_UUID plugin_id,
const ON_Layer layer,
const CRhinoMaterial *&  front_material,
const CRhinoMaterial *&  back_material 
) const

Parameters: plugin_id - [in] rendering plugin. (RhinoApp().GetDefaultRenderApp() returns the active rendering id)

layer - [in] object - [in] NULL is handled without crashing object_attributes - [in] object attributes rendering_attributes - [in] object or layer rendering attributes material_ref - [in] material reference - can be NULL

front_material - [out] Pointer to front face material (never NULL) NOTE WELL: This pointer will be invalid if the material table is changed. NEVER use this as a long term reference to a material. back_material - [out] Pointer to back face material (never NULL) NOTE WELL: This pointer will be invalid if the material table is changed. NEVER use this as a long term reference to a material. Returns: Material for object's front faces.

◆ GetMaterials() [4/4]

void CRhinoMaterialTable::GetMaterials ( const ON_UUID plugin_id,
const ON_RenderingAttributes rendering_attributes,
const CRhinoMaterial *&  front_material,
const CRhinoMaterial *&  back_material 
) const

◆ GetSortedList()

void CRhinoMaterialTable::GetSortedList ( ON_SimpleArray< const CRhinoMaterial * > &  sorted_list,
bool  bIgnoreDeleted,
bool  bIgnoreReference 
) const

Description: Gets an array of pointers to materials whose value of CRhinoMaterial.m_sort_index != -1. The returned list is sorted by the value of CRhinoMaterial.m_sort_index.

Parameters: sorted_list - [out] this array is returned with length <= MaterialCount() and is sorted by the values of CRhinoMaterial::m_sort_index.

bIgnoreDeleted - [in] true means don't include deleted materials.

bIgnoreDeleted - [in] true means don't include referenced materials. A "referenced" material is one from a worksession reference model or a linked instance definition model.

Remarks: Use Sort() to set the values of m_sort_index.

◆ InMaterialTable()

bool CRhinoMaterialTable::InMaterialTable ( const ON_Material material) const

Returns: true The material is an element in this texture mapping table.

◆ IsValidMaterialTableIndex()

bool CRhinoMaterialTable::IsValidMaterialTableIndex ( int  material_index) const

Returns: true The material_index is a valid index of a material element in this material table.

◆ ListTable()

void CRhinoMaterialTable::ListTable ( ON_TextLog text_log,
unsigned int  level_of_detail 
) const

◆ Material()

const CRhinoMaterial* CRhinoMaterialTable::Material ( const ON_ComponentManifestItem item) const

◆ MaterialCount()

int CRhinoMaterialTable::MaterialCount ( ) const

Returns: Number of materials in the material table, including deleted materials.

◆ ModifyMaterial()

bool CRhinoMaterialTable::ModifyMaterial ( const ON_Material material,
int  material_index,
bool  bQuiet = false 
)

Description: Modify material settings

Parameters: material - [in] new settings. This information is copied. material_index - [in] zero based index of material to set. This must be in the range 0 <= material_index < MaterialCount(). bQuiet - [in] if TRUE, then no message boxes pop up to explain failures.

Returns: TRUE if successful. FALSE if material_index is out of range or the settings attempt to lock or hide the current material.

◆ operator[]()

const CRhinoMaterial& CRhinoMaterialTable::operator[] ( int  material_index) const

Description: Conceptually, the material table is an array of MaterialCount() materials. The operator[] can be used to get individual materials. A material is either active or deleted and this state is reported by CRhinoMaterial::IsDeleted().

Parameters: material_index - zero based array index or -1 for the default rendering material.

Returns: Refererence to the material. If material_index is out of range, the current material is returned. Note that this reference may become invalid after AddMaterial() is called.

◆ ResetMaterial()

bool CRhinoMaterialTable::ResetMaterial ( int  material_index)

Description: Reset material to default settings. Parameters: material_index - [in] zero based index of material to reset.

◆ SetCurrentMaterialIndex()

bool CRhinoMaterialTable::SetCurrentMaterialIndex ( int  material_index,
bool  bQuiet = FALSE 
)

Description: At all times, there is a "current" material. Unless otherwise specified, new objects are assigned to the current material. The current material is never locked, hidden, or deleted.

Parameters: material_index - [in] value for new current material. -1 <= material_index < MaterialCount(). bQuiet - [in] if TRUE, then no warning message box pops up if the current material request can't be satisfied. Returns: TRUE if current material index successfully set.

◆ SetCurrentMaterialSource()

bool CRhinoMaterialTable::SetCurrentMaterialSource ( ON::object_material_source  current_material_source)

◆ SetRemapIndex()

void CRhinoMaterialTable::SetRemapIndex ( int  ,
int   
)

◆ Sort()

void CRhinoMaterialTable::Sort ( int(*)(const CRhinoMaterial *, const CRhinoMaterial *, void *)  compare,
int(*)(const CRhinoMaterial *, void *)  cull,
void *  p = 0 
)

Description: Use this to set CRhinoMaterial::m_sort_index so that the values of m_sort_index run from 0 to MaterialCount()-1 and compare(material_table[i],material_table[j]) < 0 ) implies material_table[i].m_sort_index < material_table[j].m_sort_index.

Parameters: compare - [in] compare function with prototype int compare(const CRhinoMaterial* arg1,const CRhinoMaterial* arg2,void* p). that returns <0 if arg1<arg2, 0 if arg1=arg2, and >0 if arg1>arg2. cull - [in] optional filter function with prototype int cull(const CRhinoMaterial* arg,void* p). Pass null if you do not want to cull the list. The cull() should return a non-zero value if the material should be ignored when sorting. Materials that are culled get m_sort_index set to -1. p - [in] pointer passed as last argument to compare() and cull().

Remarks: After calling Sort(), you can repeatedly call GetSortedList() to get a sorted list of CRhinoMaterial pointers. Sort() and GetSortedList() do not modify the order or persistent information in the material table. They are intended to be used to get sorted lists of materials for dialogs, etc.

◆ TableReference()

const CRhinoDocTableReference& CRhinoMaterialTable::TableReference ( ) const

◆ UndeleteMaterial()

bool CRhinoMaterialTable::UndeleteMaterial ( int  material_index)

Description: Undeletes a material that has been deleted by DeleteMaterial().

Parameters: material_index - [in] zero based index of material to undelete. This must be in the range 0 <= material_index < MaterialCount().

Returns: TRUE if successful.

◆ UndoModifyMaterial() [1/2]

bool CRhinoMaterialTable::UndoModifyMaterial ( int  material_index,
unsigned int  ur_sn = 0 
)

Description: If the material has been modified and the modification can be undone, then UndoModifyMaterial() will restore the material to its previous state.

Returns: True if this material had been modified and the modifications were undone.

See Also: CRhinoMaterial::IsModified.

◆ UndoModifyMaterial() [2/2]

bool CRhinoMaterialTable::UndoModifyMaterial ( int  )

Description: If the material has been modified and the modifcation can be undone, then UndoModify() will restore the material to its previous state.

Returns: TRUE if this material had been modified and the modifications were undone.

See Also: IsModified.

◆ WorstPossibleMaterial()

static const CRhinoMaterial& CRhinoMaterialTable::WorstPossibleMaterial ( )
static

The "WorstPossibleMaterial" is used when no document is available but poorly designed code reqires a material. This code can't possibly do anything useful because there is no context in which to use a material.

Friends And Related Function Documentation

◆ CRhinoDoc

friend class CRhinoDoc
friend

Member Data Documentation

◆ DefaultLockedMaterial

const CRhinoMaterial& CRhinoMaterialTable::DefaultLockedMaterial

default material for locked objects.

◆ DefaultMaterial

const CRhinoMaterial& CRhinoMaterialTable::DefaultMaterial

default material for unlocked objects.