Class ObjectDataReaderCallback
See Also: Class TriObject.
class ObjectDataReaderCallback
Description:
3D Studio DOS allowed developers to store APP_DATA with objects and nodes in the scene. When the 3DS DOS file is imported into 3ds max, and no plug-in has registered to convert it, then it is just hung off the object (or INode in the case of KXP app data).
A 3ds max plug-in can register itself to read a particular APP_DATA chunk when a 3DS DOS file is loaded. If a chunk is encountered that matches a registered plug-in, that plug-in will be asked to create an instance of itself based on the contents of the APP_DATA chunk. The plug-in callback is given an opportunity to read the chunk and create an object other than a TriObject based on the contents of the chunk and the original object.
A plug-in that wants to process app data registers a new class derived from this class by calling void RegisterObjectAppDataReader(ObjectDataReaderCallback *cb);
The system then maintains a list of these ObjectDataReaderCallbacks.
Methods:
Prototype:
virtual char *DataName()=0;
Remarks:
Implemented by the Plug-In.
Returns the name that identifies the app data chunk. When the 3DS Import plug-in is loading objects, it will look for app data. For each app data chunk that the object has, it will go through the list of registered callbacks and call this method looking for a name match. When it does find a match it will call ReadData() on the callback that matched.
Prototype:
virtual Object *ReadData(TriObject *obj, void *data, DWORD len)=0;
Remarks:
Implemented by the Plug-In.
This method is called to read the app data and create an instance of an object based on the data and the original mesh object. For example, the 3D Surfer plug-in from 3DS DOS creates a patch object based on the app data parameters and returns a pointer to it.
Parameters:
TriObject *obj
The original mesh object the app data was assigned to. If no callback was registered, this would be the object that would get created.
void *data
Points to the particular app data chunk handled by the registered callback.
DWORD len
The length of the app data chunk.
Return Value:
The Object created by the plug-in to hold the appdata. This would be the object created to take the place of the TriObject. For example, consider a 3DS object that had appdata embedded in it which represented the patch object from which the mesh was created (like 3D Surfer for example). This method would take that data and created a patch object so that the user could work with the object as a patch object in 3ds max instead of a tri object.
Prototype:
virtual void DeleteThis()=0;
Remarks:
Implemented by the Plug-In.
This method is called to delete this callback object. When the user exits 3ds max, this method is called on each of the registered callbacks. So if the callback was allocated dynamically, it could free itself in this implementation.
The following functions are not part of any class but are available for use:
Prototype:
void RegisterObjectAppDataReader(ObjectDataReaderCallback *cb);
Remarks:
Implemented by the System.
This method allows a plug-in to register a callback that will be called when reading a 3DS file that has a particular appdata chunk. The plug-in callback is given an opportunity to read the chunk and create an object other than a TriObject based on the contents of the chunk and the original object.
Parameters:
ObjectDataReaderCallback *cb
The callback to read the chunk and create an object.
Prototype:
Object *ObjectFromAppData(TriObject *obj, char *name, void *data, DWORD len);
Remarks:
This function is used internally by the 3DS Import plug-in.
Note the following about 3DS App Data. If app data is encountered and no plug-in has registered to convert it, then it is just hung off the object (or INode in the case of KXP app data). For object app data, TriObject's super class and class ID are used to identify the chunk and the sub ID is set to 0. For node app data, INode's super class and class ID are used to identify the chunk and the sub ID is set to 0.
This single 3ds max app data chunk will contain the entire 3DS app data chunk, which may have sub chunks (see the IPAS SDK). The following routines will aid in parsing 3DS app data.
Prototype:
void GetIDStr(char *chunk, char *idstring);
Remarks:
This function gets the ID string out of an XDATA_ENTRY chunk and null terminates it.
Parameters:
char *chunk
A pointer to the chunk.
char *idstring
The ID string.
Prototype:
int FindAppDataChunk(void *appd, DWORD len, char *idstring);
Remarks:
Returns the offset into appd of the specified chunk or -1 if it is not found.
Parameters:
void *appd
The is the entire app data chunk containing all the sub-chunks.
DWORD len
This is the length of the entire app data chunk.
char *idstring
The ID of the chunk to find.
Return Value:
The offset into appd of the specified chunk or -1 if it is not found.
Prototype:
void *GetAppDataChunk(void *appd, DWORD len, char *idstring);
Remarks:
This function is similar to FindAppDataChunk() above, but returns a pointer to the chunk or NULL if it is not found.
Parameters:
void *appd
The is the entire app data chunk containing all the sub-chunks.
DWORD len
This is the length of the entire app data chunk.
char *idstring
The ID of the chunk to find.
Return Value:
A pointer to the chunk or NULL if it is not found.
Prototype:
int SetAppDataChunk(void **pappd, DWORD &len, void *chunk);
Remarks:
This function adds the chunk to the appdata chunk, preserving existing chunks. chunk should point to the new chunk header followed by its data.
Parameters:
void **pappd
The is the entire app data chunk containing all the sub-chunks.
DWORD &len
This is the length of the entire app data chunk.
void *chunk
A pointer to the new chunk header.
Return Value:
Nonzero if the chunk was added; otherwise zero.
Prototype:
int DeleteAppDataChunk(void **pappd, DWORD &len, char *idstring);
Remarks:
Deletes a chunk from the appdata while preserving other chunks.
Parameters:
void **pappd
The is the entire app data chunk containing all the sub-chunks.
DWORD &len
This is the length of the entire app data chunk.
char *idstring
The ID of the chunk to delete.
Return Value:
Nonzero if the chunk was deleted; otherwise zero.