# IRfReferencedMaterials Interface Reference

Inherits IUnknown.

List of all members.

## Public Member Functions
HRESULT | GetGlobalMaterialsEncapsulator ([out] IRnEncapsulator **ppEnc)
HRESULT | CreateGlobalMaterialsEncapsulator ([out] IRnEncapsulator **ppEnc)
HRESULT | GetObjectMaterialsEncapsulator ([in] IRsNode *pNode,[out] IRnEncapsulator **ppEnc)
HRESULT | CreateObjectMaterialsEncapsulator ([in] IRsNode *pNode,[out] IRnEncapsulator **ppEnc)
HRESULT | SetMaterialId ([in] IRsNode *pMaterialNode,[in] GUID gId)
HRESULT | GetMaterialId ([in] IRsNode *pMaterialNode,[out] GUID *gId)
HRESULT | UpdateMaterialLinks ([in] IRsNode *pMaterialNode)
HRESULT | GetReferencedMaterialNode ([in] IRnMaterialReference *pRefMat,[out] IRsNode **ppSharedMaterialNode)
HRESULT | ReplaceMaterialReferences ([in] GUID *pId,[in] IRsNode *pObjectRoot,[in] IRsNode *pSharedMaterialNode)
HRESULT | LocateMaterialNode ([in] GUID *pId,[in] IRnEncapsulator *pEncaps,[out] IRsNode **ppMaterial)
HRESULT | RemoveUnusedMaterials ([in] IRnEncapsulator *pMatEnc)
HRESULT | GetMaterialReferencesCount ([in] IRsNode *pNode,[out] RtUlong *pdwNum)
HRESULT | CleanupSharedMaterialEncapsulator (IRnEncapsulator *pMatEnc)

## Detailed Description

Referenced materials management and helper function set.

## Member Function Documentation

HRESULT IRfReferencedMaterials::GetGlobalMaterialsEncapsulator | ( | [out] IRnEncapsulator ** | ppEnc | ) |

Return global (scene) shared materials encapsulator.

- If none is present, E_FAIL is returned.

Parameters:

  | ppEnc | [out] Filled with global material encapsulator (if present).

Returns:
  S_OK if succeeded.

HRESULT IRfReferencedMaterials::CreateGlobalMaterialsEncapsulator | ( | [out] IRnEncapsulator ** | ppEnc | ) |

Return global (scene) shared materials encapsulator.

- If none is present, it is created.

Parameters:

  | ppEnc | [out] Filled with global material encapsulator (if present).

Returns:
  S_OK if material encapsulator created, S_FALSE if already existed.

HRESULT IRfReferencedMaterials::GetObjectMaterialsEncapsulator | ( | [in] IRsNode * | pNode,
|  | [out] IRnEncapsulator ** | ppEnc |
| ) |  |  |

Return object shared materials encapsulator.

- If none is present, E_FAIL is returned.

Parameters:

  | pNode | [in] Node for which shared material encapsulator is requested.
  | ppEnc | [out] Filled with material encapsulator (if present).

Returns:
  S_OK if succeeded.

HRESULT IRfReferencedMaterials::CreateObjectMaterialsEncapsulator | ( | [in] IRsNode * | pNode,
|  | [out] IRnEncapsulator ** | ppEnc |
| ) |  |  |

CreateObjectMaterialsEncapsulator creates material instancing encapsulator inside specified node.

Parameters:

  | pNode | [in] Node for which object material instancing encapsulator should be created
  | ppEnc | [out] Filled with material encapsulator

Returns:
  S_OK if material encapsulator created, S_FALSE if already exists.

HRESULT IRfReferencedMaterials::SetMaterialId | ( | [in] IRsNode * | pMaterialNode,
|  | [in] GUID | gId |
| ) |  |  |

Set material ID to shared material.

- Material ID is stored in global hidden connector (CON_MATERIAL_SHARED_ID).
- Material ID is used for identification when re-linking shared materials with material reference nodes.

Parameters:

  | pMaterialNode | [in] Material encapsulator node.
  | gId | [in] ID to set.

Returns:
  S_OK if succeeded.

HRESULT IRfReferencedMaterials::GetMaterialId | ( | [in] IRsNode * | pMaterialNode,
|  | [out] GUID * | gId |
| ) |  |  |

Get material ID to shared material.

Parameters:

  | pMaterialNode | [in] Material encapsulator node.
  | gId | [out] ID to set.

Returns:
  S_OK if succeeded.

HRESULT IRfReferencedMaterials::UpdateMaterialLinks | ( | [in] IRsNode * | pMaterialNode | ) |

Update missing material references based on material IDs.

Parameters:

  | pMaterialNode | [in] Material node (any node exporting CON_MATERIAL_CHUNK connector).

Returns:
  S_OK if succeeded.

HRESULT IRfReferencedMaterials::GetReferencedMaterialNode | ( | [in] IRnMaterialReference * | pRefMat,
|  | [out] IRsNode ** | ppSharedMaterialNode |
| ) |  |  |

Return shared material node referenced by material reference.

- If reference material link is missing, function fails.

Parameters:

  | pRefMat | [in] Referenced material.
  | ppSharedMaterialNode | [out] Filled with shared material node.

Returns:
  S_OK if succeeded.

HRESULT IRfReferencedMaterials::ReplaceMaterialReferences | ( | [in] GUID * | pId,
|  | [in] IRsNode * | pObjectRoot,
|  | [in] IRsNode * | pSharedMaterialNode |
| ) |  |  |

Relink referenced materials identified by id with provided material.

Parameters:

  | pId | [in] Material ID to relink.
  | pObjectRoot | [in] Object root of sub-object to scan.
  | pSharedMaterialNode | [in] Material node to link to.

Returns:
  S_OK if succeeded.

HRESULT IRfReferencedMaterials::LocateMaterialNode | ( | [in] GUID * | pId,
|  | [in] IRnEncapsulator * | pEncaps,
|  | [out] IRsNode ** | ppMaterial |
| ) |  |  |

Locate material with specified ID inside defined encapsulator.

Parameters:

  | pId | [in] Material ID to find.
  | pEncaps | [in] Encapsulator to search.
  | ppMaterial | [out] Material node with specified ID if found.

Returns:
  S_OK if succeeded.

HRESULT IRfReferencedMaterials::RemoveUnusedMaterials | ( | [in] IRnEncapsulator * | pMatEnc | ) |

Search referenced material encapsulator and remove unused materials.

Parameters:

  | pMatEnc | [in] Encapsulator to scan.

Returns:
  S_OK if succeeded.

HRESULT IRfReferencedMaterials::GetMaterialReferencesCount | ( | [in] IRsNode * | pNode,
|  | [out] RtUlong * | pdwNum |
| ) |  |  |

Get number of references for specified material.

Parameters:

  | pNode | [in] Material.
  | pdwNum | [out] Number of references.

Returns:
  S_OK if succeeded.

HRESULT IRfReferencedMaterials::CleanupSharedMaterialEncapsulator | ( | IRnEncapsulator * | pMatEnc | ) |

Remove referenced materials encapsulator if it is not required anymore (empty).

Parameters:

  | pMatEnc | [in] Material encapsulator.

Returns:
  S_OK if succeeded.