This reference page is linked to from the following overview topics: XRef Scenes and Objects.
Detailed Description
Class for managing an object xref record.
Xref records store xref items and information regarding the xref operation/transaction that created them. Xref records are created by and can be retrieved from the Object Xref Manager (see class IObjXRefManager8). Xref records are not created when xrefing a whole scene via the scene xref feature.
#include <iXRefObjRecord.h>
Public Types |
|
| enum | FPFuncIDs
{ kfpItemCount, kfpIsEmpty, kfpGetItem, kfpGetItems, kfpGetChildRecords, kfpGetParentRecords, kfpGetRootRecords, kfpIsNested, kfpGetIncludeAll, kfpSetIncludeAll, kfpGetAutoUpdate, kfpSetAutoUpdate, kfpGetEnabled, kfpSetEnabled, kfpGetUpToDate, kfpSetUpToDate, kfpCheckSrcFileChanged, kfpIsUnresolved, kfpGetSrcFileName, kfpSetSrcFileName, kfpGetSrcFileAssetId, kfpSetSrcFileAssetId, kfpUpdate, kfpGetRecordId, kfpGetHandle, kfpGetXRefOptions } |
| enum | FPEnums { kfpXRefItemTypes, kfpXRefItemTypesNoAll, kfpXrefOptions } |
Public Member Functions |
|
| virtual Interface_ID | GetID () |
| virtual FPInterfaceDesc * | GetDesc () |
| BEGIN_FUNCTION_MAP | FN_1 (kfpItemCount, TYPE_DWORD, FPItemCount, TYPE_ENUM_TAB_BR) |
| FN_2 (kfpGetItem, TYPE_REFTARG, FPGetItem, TYPE_INDEX, TYPE_ENUM) | |
| FN_2 (kfpGetItems, TYPE_DWORD, FPGetItems, TYPE_ENUM_TAB_BR, TYPE_REFTARG_TAB_BR) | |
| FN_1 (kfpGetChildRecords, TYPE_DWORD, FPGetChildRecords, TYPE_INTERFACE_TAB_BR) | |
| FN_1 (kfpGetParentRecords, TYPE_DWORD, FPGetParentRecords, TYPE_INTERFACE_TAB_BR) | |
| FN_1 (kfpGetRootRecords, TYPE_DWORD, FPGetRootRecords, TYPE_INTERFACE_TAB_BR) | |
| FN_0 (kfpCheckSrcFileChanged, TYPE_bool, CheckSrcFileChanged) | |
| FN_0 (kfpUpdate, TYPE_bool, Update) | |
| PROP_FNS (kfpGetIncludeAll, IsIncludeAll, kfpSetIncludeAll, SetIncludeAll, TYPE_bool) | |
| PROP_FNS (kfpGetAutoUpdate, IsAutoUpdate, kfpSetAutoUpdate, SetAutoUpdate, TYPE_bool) | |
| PROP_FNS (kfpGetEnabled, IsEnabled, kfpSetEnabled, SetEnable, TYPE_bool) | |
| PROP_FNS (kfpGetUpToDate, GetUpToDate, kfpSetUpToDate, SetUpToDate, TYPE_bool) | |
| RO_PROP_FN (kfpIsEmpty, IsEmpty, TYPE_bool) | |
| RO_PROP_FN (kfpIsUnresolved, IsUnresolved, TYPE_bool) | |
| PROP_FNS (kfpGetSrcFileName, FPGetSrcFileName, kfpSetSrcFileName, FPSetSrcFileName, TYPE_FILENAME) | |
| RO_PROP_FN (kfpGetHandle, GetHandle, TYPE_DWORD) | |
| RO_PROP_FN (kfpGetXRefOptions, FPGetXRefOptions, TYPE_ENUM_TAB_BV) | |
| RO_PROP_FN (kfpIsNested, IsNested, TYPE_bool) | |
|
XRef Item Access
|
|
| virtual unsigned int | ItemCount (IXRefItem::XRefItemType itemType) const =0 |
| Retrieves the number of xref items stored in
this record. |
|
| virtual unsigned int | GetItems (IXRefItem::XRefItemType itemType, Tab< ReferenceTarget * > &xrefItems) const =0 |
| Retrieves all the xref items of the
specified type. |
|
| virtual ReferenceTarget * | GetItem (unsigned int i, IXRefItem::XRefItemType itemType) const =0 |
| Retrieves the i-th xref item of the
specified type. |
|
| virtual bool | IsEmpty () const =0 |
| Allows to verify whether this record
contains any xref items. |
|
|
Nested XRef Record Management
|
|
|
When xrefing scene entities that are themselves xrefs, nested xref records are created. The following methods allow finding and working with nested xref records. |
|
| virtual unsigned int | GetChildRecords (Tab< IObjXRefRecord * > &childRecords) const =0 |
| Retrieves all child xref records of this
record. |
|
| virtual unsigned int | GetParentRecords (Tab< IObjXRefRecord * > &parentRecords) const =0 |
| Retrieves all parent xref records of this
record. |
|
| virtual unsigned int | GetRootRecords (Tab< IObjXRefRecord * > &rootRecords) const =0 |
| Retrieves all root (top-level) xref records
of this record. |
|
| virtual bool | IsNested () const =0 |
| Retrives whether this xref record has parent
records or not. |
|
|
XRef Record State Access
|
|
|
The following methods allow for setting and retrieving options used when xrefing scene entities. These options apply to the whole xrefing operation rather than to individual xref items. |
|
| virtual unsigned int | GetXRefOptions () const =0 |
| Retrives the options used to create this
xref record. |
|
| virtual bool | IsIncludeAll () const =0 |
| Retrieves whether all scene entities are
xrefed from this record's source file. |
|
| virtual void | SetIncludeAll (bool bEnable)=0 |
| Sets the xrefing of all scene entities from
this record's source file. |
|
| virtual bool | IsEnabled () const =0 |
| Retrieves the enabled state of this xref
record. |
|
| virtual void | SetEnable (bool bEnable)=0 |
| Sets the enabled state of this xref record.
|
|
| virtual bool | IsAutoUpdate () const =0 |
| Retrieves whether auto-update is enabled for
this xref record. |
|
| virtual void | SetAutoUpdate (bool bEnable)=0 |
| Sets the state of the auto-upate for this
xref record. |
|
| virtual bool | GetUpToDate () const =0 |
| Allows to verify whether the xref record is
up-to-date. |
|
| virtual void | SetUpToDate (bool bUpToDate)=0 |
| Allows to set an xref record as out-of-date.
|
|
| virtual bool | CheckSrcFileChanged ()=0 |
| Verifies whether the source file of this
xref record has changed since the record was last updated. |
|
| virtual bool | IsUnresolved () const =0 |
| Allows to verify whether the xref record is
unresolved. |
|
| virtual
const MaxSDK::AssetManagement::AssetUser & |
GetSrcFile () const =0 |
| Retrieves the asset Id of the source file.
|
|
| virtual const MSTR & | GetParentSrcFileName () const =0 |
| Returns the parent Xref record source file
name. |
|
|
XRef Record Management
|
|
| virtual bool | Update ()=0 |
| Updates the xref record by reloading its
xref items from the source file. |
|
| virtual XRefRecordHandle | GetHandle () const =0 |
| Retrieves the record's unique handle.
|
|
Static Public Member Functions |
|
| static IObjXRefRecord * | GetInterface (InterfaceServer *is) |
| Retrieves the IObjXRefRecord
interface from an InterfaceServer. |
|
Member Enumeration Documentation
| enum FPFuncIDs |
- Enumerator:
{
kfpItemCount,
kfpIsEmpty,
kfpGetItem,
kfpGetItems,
kfpGetChildRecords,
kfpGetParentRecords,
kfpGetRootRecords,
kfpIsNested,
kfpGetIncludeAll, kfpSetIncludeAll,
kfpGetAutoUpdate, kfpSetAutoUpdate,
kfpGetEnabled, kfpSetEnabled,
kfpGetUpToDate, kfpSetUpToDate,
kfpCheckSrcFileChanged,
kfpIsUnresolved,
kfpGetSrcFileName, kfpSetSrcFileName,
kfpGetSrcFileAssetId, kfpSetSrcFileAssetId,
kfpUpdate,
kfpGetRecordId,
kfpGetHandle,
kfpGetXRefOptions,
};
| enum FPEnums |
Member Function Documentation
| virtual unsigned int ItemCount | ( | IXRefItem::XRefItemType | itemType | ) | const [pure virtual] |
Retrieves the number of xref items stored in this record.
- Parameters:
-
[in] itemType - One of the predefined xref item types IXRefItem::XRefItemType
- Returns:
- - The number of xrefed items of the specified type.
| virtual unsigned int GetItems | ( | IXRefItem::XRefItemType | itemType, |
| Tab< ReferenceTarget * > & | xrefItems | ||
| ) | const [pure virtual] |
Retrieves all the xref items of the specified type.
Note that any xref atmospheric item returned by this method will become invalid if all other types of items are removed from this record. Also, any of of the xref items returned by this method could become invalid after an operation that modifies the contents of the xref record.
- Parameters:
-
[in] itemType - A combination of predefined xref item types IXRefItem::XRefItemType [in,out] xrefItems - An array where the xref items will be returned. The array is not cleared, so its existent elements will be preserved.
- Returns:
- - The number of returned xref items
| virtual ReferenceTarget* GetItem | ( | unsigned int | i, |
| IXRefItem::XRefItemType | itemType | ||
| ) | const [pure virtual] |
Retrieves the i-th xref item of the specified type.
- Parameters:
-
[in] i - The index of the xref item to retrieve. [in] itemType - One of the predefined xref item types IXRefItem::XRefItemType
- Returns:
- - Pointer to the xref item. NULL if the supplied index (i) is out of range, or if the supplied item type is unsupported
| virtual bool IsEmpty | ( | ) | const [pure virtual] |
Allows to verify whether this record contains any xref items.
Note that empty xref records are automatically deleted by the system, so this method should never return true, except when called before the system had a chance to delete empty xref records. Also note that xref records containing only xref atmospherics will be deleted automatically by the system.
- Returns:
- - true if the record does not contain any xref items of any type, otherwise false
| virtual unsigned int GetChildRecords | ( | Tab< IObjXRefRecord * > & | childRecords | ) | const [pure virtual] |
Retrieves all child xref records of this record.
- Parameters:
-
[out] childRecords - Array of xref records where the child records are retured. The supplied array is not cleared out before the xref records are added to it. The array is guaranteed not to contain duplicate xref records.
- Returns:
- - The number of child xref records.
| virtual unsigned int GetParentRecords | ( | Tab< IObjXRefRecord * > & | parentRecords | ) | const [pure virtual] |
Retrieves all parent xref records of this record.
- Parameters:
-
[out] parentRecords - Array of xref records where the parent records are returned. The supplied array is not cleared out before the xref records are added to it. The array is guaranteed not to contain duplicate xref records.
- Returns:
- - The number of parent xref records.
| virtual unsigned int GetRootRecords | ( | Tab< IObjXRefRecord * > & | rootRecords | ) | const [pure virtual] |
Retrieves all root (top-level) xref records of this record.
- Parameters:
-
[out] rootRecords - Array of xref records where the root records are returned. The supplied array cleared out before the xref records are added to it. The array is guaranteed not to contain duplicate xref records.
- Returns:
- - The number of root xref records.
| virtual bool IsNested | ( | ) | const [pure virtual] |
Retrives whether this xref record has parent records or not.
This method uses a more efficient way of determining whether this xref record is nested or not than calling GetParentRecords.
- Returns:
- - true if this xref record is nested, i.e. has at least one parent record, otherwise false.
| virtual unsigned int GetXRefOptions | ( | ) | const [pure virtual] |
Retrives the options used to create this xref record.
These options cannot be modifed once the xref record has been created.
- Returns:
- The options used to create the xref record. See Object Xref Options for a full list of available options.
- See also:
- IObjXRefManager8::XRefAllObjectsFromFile
| virtual bool IsIncludeAll | ( | ) | const [pure virtual] |
Retrieves whether all scene entities are xrefed from this record's source file.
When this option is turned on, the next update operation of this xref record will xref all scene entities that have not been xrefed yet from the its source file.
- Returns:
- - true if this should be xrefing all scene entities from its source file, otherwise false
| virtual void SetIncludeAll | ( | bool | bEnable | ) | [pure virtual] |
Sets the xrefing of all scene entities from this record's source file.
- Parameters:
-
[in] bEnable - If true, the include-all option is enabled, otherwise it's disabled
| virtual bool IsEnabled | ( | ) | const [pure virtual] |
Retrieves the enabled state of this xref record.
Enabled xref records can be updated, while disabled xref records cannot.
- Returns:
- - true if this xref record is enabled, otherwise false
- See also:
- IObjXRefRecord::Update
| virtual void SetEnable | ( | bool | bEnable | ) | [pure virtual] |
Sets the enabled state of this xref record.
When disabling an xref record, the source items of its xref items are un-loaded from memory. Note that opening a master file containing disabled xref records results in unresolved xref items. Re-enabling and updating the record, re-resolves the xref items.
- Parameters:
-
[in] bEnable - If true, the xref record is enabled, otherwise it's disabled
| virtual bool IsAutoUpdate | ( | ) | const [pure virtual] |
Retrieves whether auto-update is enabled for this xref record.
When Auto-update is enabled, the xref record is automatically updated as soon as the source file changes.
- Returns:
- - true if this xref record is has auto-update turned on, otherwise false
| virtual void SetAutoUpdate | ( | bool | bEnable | ) | [pure virtual] |
Sets the state of the auto-upate for this xref record.
- Parameters:
-
[in] bEnable - If true, auto-update is enabled for this xref record, otherwise it's disabled.
| virtual bool GetUpToDate | ( | ) | const [pure virtual] |
Allows to verify whether the xref record is up-to-date.
The xref record is up-to-date if it's been updated with the source items from the latest version of the source file. This method will report the current value of the up-to-date state of this xref record. To trigger a verification of whether the source file of this xref record has changed, use CheckSrcFileChanged.
- Returns:
- - true if the record is up-to-date, otherwise false
| virtual void SetUpToDate | ( | bool | bUpToDate | ) | [pure virtual] |
Allows to set an xref record as out-of-date.
Only out-of-date records are processed by an update request.
- Parameters:
-
[in] bUpToDate - false to set the record as ou-of-date, otherwise true
| virtual bool CheckSrcFileChanged | ( | ) | [pure virtual] |
Verifies whether the source file of this xref record has changed since the record was last updated.
Calling this method checks whether the source file is unresolved. If it isn't, it updates the up-to-date flag of this xref record by comparing the date and time of the source file with the date and time the xref record was last updated.
- Returns:
- - true if the unresolved state, or the up-to-date state have changed, false if neither have changed
| virtual bool IsUnresolved | ( | ) | const [pure virtual] |
Allows to verify whether the xref record is unresolved.
An xref record is unresolved if the source file name and path is not valid. Unresolved xref records are not discarded by the system because they may get re-resolved on a subsequent update of the xref record if the source file path and name becomes valid.
- Returns:
- - true if this is an unresolved xref record, otherwise false
| virtual const MaxSDK::AssetManagement::AssetUser& GetSrcFile | ( | ) | const [pure virtual] |
Retrieves the asset Id of the source file.
The source file of an xref record is the file from where the source scene entities xrefed via this xref record come from.
- Returns:
- - The asset user of the file that the source scene entity comes from or or NULL if there's no source file specified.
| virtual const MSTR& GetParentSrcFileName | ( | ) | const [pure virtual] |
Returns the parent Xref record source file name.
- Returns:
- the parent source file name.
| virtual bool Update | ( | ) | [pure virtual] |
Updates the xref record by reloading its xref items from the source file.
The xref entities are reloaded according to the currently set options. For example, the xref record will not be updated if it is disabled.
- Note:
- Updating an xref record will trigger the updating of all nested xref records.
- Updating an xref record with the Include All flag On for itself and all its child records, will not result in xrefing scene entities newly added to nested source files. The child xref records saved with the intermediate master files must be update first, starting with the deepest child or intermediate file.
- Returns:
- - true if the operation succeeded, otherwise false.
| virtual XRefRecordHandle GetHandle | ( | ) | const [pure virtual] |
Retrieves the record's unique handle.
Each xref record is identified by a unique handle. The handle value is unique only within the current scene. Reseting the scene is considered to start a new scene. The handle of the xref records is not persisted.
- Returns:
- - The handle of this xref record.
- See also:
- XRefRecordHandle
| static IObjXRefRecord* GetInterface | ( | InterfaceServer * | is | ) | [inline, static] |
Retrieves the IObjXRefRecord interface from an InterfaceServer.
- Parameters:
-
[in] is - Pointer to InterfaceServer
- Returns:
- - Pointer to the IObjXRefRecord interface of the scene entity or NULL if it's not an xref record
{
DbgAssert(is != NULL);
return static_cast<IObjXRefRecord*>(is->GetInterface(IID_XREF_OBJ_RECORD));
};
| virtual Interface_ID GetID | ( | ) | [inline, virtual] |
- Remarks:
- This method overrides GetID() in those interfaces that do not publish metadata but instead have a unique Interface_ID for quick internal identification in implementation code that might be shared by a bunch of mixin interfaces.
- Returns:
- The Interface_ID.
- Default Implementation:
- { return GetDesc()->ID; }
Reimplemented from FPMixinInterface.
{ return IID_XREF_OBJ_RECORD; }
| virtual FPInterfaceDesc* GetDesc | ( | ) | [inline, virtual] |
- Remarks:
- Returns a pointer to the class which contains the interface metadata.
Implements FPInterface.
{ return &mFPInterfaceDesc; }
| BEGIN_FUNCTION_MAP FN_1 | ( | kfpItemCount | , |
| TYPE_DWORD | , | ||
| FPItemCount | , | ||
| TYPE_ENUM_TAB_BR | |||
| ) |
| FN_2 | ( | kfpGetItem | , |
| TYPE_REFTARG | , | ||
| FPGetItem | , | ||
| TYPE_INDEX | , | ||
| TYPE_ENUM | |||
| ) |
| FN_2 | ( | kfpGetItems | , |
| TYPE_DWORD | , | ||
| FPGetItems | , | ||
| TYPE_ENUM_TAB_BR | , | ||
| TYPE_REFTARG_TAB_BR | |||
| ) |
| FN_1 | ( | kfpGetChildRecords | , |
| TYPE_DWORD | , | ||
| FPGetChildRecords | , | ||
| TYPE_INTERFACE_TAB_BR | |||
| ) |
| FN_1 | ( | kfpGetParentRecords | , |
| TYPE_DWORD | , | ||
| FPGetParentRecords | , | ||
| TYPE_INTERFACE_TAB_BR | |||
| ) |
| FN_1 | ( | kfpGetRootRecords | , |
| TYPE_DWORD | , | ||
| FPGetRootRecords | , | ||
| TYPE_INTERFACE_TAB_BR | |||
| ) |
| FN_0 | ( | kfpCheckSrcFileChanged | , |
| TYPE_bool | , | ||
| CheckSrcFileChanged | |||
| ) |
| FN_0 | ( | kfpUpdate | , |
| TYPE_bool | , | ||
| Update | |||
| ) |
| PROP_FNS | ( | kfpGetIncludeAll | , |
| IsIncludeAll | , | ||
| kfpSetIncludeAll | , | ||
| SetIncludeAll | , | ||
| TYPE_bool | |||
| ) |
| PROP_FNS | ( | kfpGetAutoUpdate | , |
| IsAutoUpdate | , | ||
| kfpSetAutoUpdate | , | ||
| SetAutoUpdate | , | ||
| TYPE_bool | |||
| ) |
| PROP_FNS | ( | kfpGetEnabled | , |
| IsEnabled | , | ||
| kfpSetEnabled | , | ||
| SetEnable | , | ||
| TYPE_bool | |||
| ) |
| PROP_FNS | ( | kfpGetUpToDate | , |
| GetUpToDate | , | ||
| kfpSetUpToDate | , | ||
| SetUpToDate | , | ||
| TYPE_bool | |||
| ) |
| RO_PROP_FN | ( | kfpIsEmpty | , |
| IsEmpty | , | ||
| TYPE_bool | |||
| ) |
| RO_PROP_FN | ( | kfpIsUnresolved | , |
| IsUnresolved | , | ||
| TYPE_bool | |||
| ) |
| PROP_FNS | ( | kfpGetSrcFileName | , |
| FPGetSrcFileName | , | ||
| kfpSetSrcFileName | , | ||
| FPSetSrcFileName | , | ||
| TYPE_FILENAME | |||
| ) |
| RO_PROP_FN | ( | kfpGetHandle | , |
| GetHandle | , | ||
| TYPE_DWORD | |||
| ) |
| RO_PROP_FN | ( | kfpGetXRefOptions | , |
| FPGetXRefOptions | , | ||
| TYPE_ENUM_TAB_BV | |||
| ) |
| RO_PROP_FN | ( | kfpIsNested | , |
| IsNested | , | ||
| TYPE_bool | |||
| ) |
