Class ILoad
See Also: Loading and Saving, Character Strings, Class ISave, Class PostLoadCallback, Class INode, Class ClassDesc, Class ClassDirectory, Class Interface.
class ILoad : public InterfaceServer
Description:
This class provides methods to load data from disk and to register post load callbacks.
Note: It is not valid, to write two CStrs in the same chunk of a 3ds max file, since ILoad::ReadCStringChunk() sets the size for the string to the ChunkSize. However it is possible to write other data, such as two ints, into the same chunk.
All methods of this class are implemented by the system.
Methods:
Prototype:
virtual IOResult OpenChunk()=0;
Remarks:
This method is used to open a chunk. If OpenChunk() returns IO_OK, use the following 3 functions to get the info about the chunk. If it returns IO_END this indicates there are no more chunks at this level.
Return Value:
IO_OK - The result was acceptable - no errors.
IO_END - This is returned from ILoad::OpenChunk() when the end of the chunks at a certain level have been reached. It is used as a signal to terminates the processing of chunks at that level.
IO_ERROR - This is returned if an error occurred. Note that the plug-in should not put up a message box if a read error occurred. It should simply return the error status. This prevents a overabundance of messages from appearing.
Prototype:
virtual USHORT CurChunkID()=0;
Remarks:
This method returns the ID of the most recently opened chunk.
Prototype:
virtual ChunkType CurChunkType()=0;
Remarks:
This method returns the type of the most recently opened chunk. This may be one of the following values:
NEW_CHUNK
CONTAINER_CHUNK
DATA_CHUNK
Prototype:
virtual ULONG CurChunkLength()=0;
Remarks:
This method returns the chunk length NOT including the header.
Prototype:
virtual int CurChunkDepth()=0;
Remarks:
This method is used internally for checking for balanced OpenChunk/CloseChunk pairs.
Prototype:
virtual USHORT PeekNextChunkID()=0;
Remarks:
This method returns the ID of the next chunk without opening it. It returns 0 if there are no more chunks.
Prototype:
virtual IOResult CloseChunk()=0;
Remarks:
This method is used to close the currently opened chunk, and position at the next chunk.
Return Value:
A return value of IO_ERROR indicates there is no open chunk to close; otherwise IO_OK.
Prototype:
virtual IOResult Read(void *buf, ULONG nbytes, ULONG *nread)=0;
Remarks:
This method is used to read a block of bytes from the output stream.
Parameters:
void *buf
A pointer to the buffer to read.
ULONG nbytes
The number of bytes to read.
ULONG *nread
The number of bytes that were read.
Return Value:
A return value of IO_ERROR indicates an error occurred, otherwise IO_OK.
Prototype:
virtual IOResult ReadWStringChunk(char** buf)=0;
Remarks:
This method read a string that was stored as Wide characters. Note: This method reads a string from a string chunk. It is assumed the chunk is already open, it will NOT close the chunk.
Parameters:
char** buf
A pointer to an array of characters.
Return Value:
A return value of IO_ERROR indicates an error occurred, otherwise IO_OK.
Prototype:
virtual IOResult ReadWStringChunk(wchar_t** buf)=0;
Remarks:
This method read a string that was stored as Wide chars. Note: This method reads a string from a string chunk. It is assumed the chunk is already open, it will NOT close the chunk.
Parameters:
wchar_t** buf
A pointer to an array of wide characters.
Return Value:
A return value of IO_ERROR indicates an error occurred, otherwise IO_OK.
Prototype:
virtual IOResult ReadCStringChunk(char** buf)=0;
Remarks:
This method reads a string that was stored as single byte characters.
Parameters:
char** buf
A pointer to an array of single byte characters. This method will allocate an internal buffer, stored in the ILoadImp class that is big enough to hold the string chunk read in. You must then copy or parse out the data and store it in your own area: you can't hang on to the string pointer it hands back because it will not be valid.
Return Value:
A return value of IO_ERROR indicates an error occurred, otherwise IO_OK.
Prototype:
virtual IOResult ReadCStringChunk(wchar_t** buf)=0;
Remarks:
This method may be used to read a string that was stored as single byte characters.
Parameters:
wchar_t** buf
A pointer to an array of wide characters. This method will allocate an internal buffer, stored in the ILoadImp class that is big enough to hold the string chunk read in. You must then copy or parse out the data and store it in your own area: you can't hang on to the string pointer it hands back because it will not be valid.
Return Value:
A return value of IO_ERROR indicates an error occurred, otherwise IO_OK.
Prototype:
virtual void SetObsolete()=0;
Remarks:
You may call this if you encounter obsolete data to cause a message to be displayed after loading.
Prototype:
virtual void RegisterPostLoadCallback(PostLoadCallback *cb)=0;
Remarks:
Registers a procedure to be called after loading. These will be called in the order that they are registered. It is assumed that if the callback needs to be deleted, the proc will do it.
Parameters:
PostLoadCallback *cb
Points to the callback object.
Prototype:
virtual TCHAR *GetDir(int which)=0;
Remarks:
Retrieves the specified standard 3ds max directory name (fonts, scenes, images, ...).
Parameters:
int which
Specifies the directory name to retrieve. See List of Directory Names. The constants are defined in MAXAPI.H
Return Value:
The name of the specified directory.
Prototype:
virtual void RecordBackpatch(int imaker, void** patchThis, DWORD flags = 0)=0;
Remarks:
This method may be used to load a pointer from disk. This is a pointer that was saved using ISave::GetRefID(). You pass the index returned from GetRefID() and a pointer to a pointer that will get set. This method will patch the address immediately if it is available, otherwise it will happen later when it is known. During the load process if you need to work with this information you'll have to use a post load callback since all the addresses are not updated immediately. See RegisterPostLoadCallback() above.
Parameters:
int imaker
This is the index returned from ISave::GetRefID().
void** patchThis
This is a pointer to the pointer you want patched.
DWORD flags = 0
This flag indicates that backpatches (and their subsequent references) should be merged as well.
Prototype:
virtual void* GetAddr(int imaker)=0;
Remarks:
This method may be used to load a pointer from disk. It returns the memory address of the specified object Scene stream. This may be NULL if the address is not available. See RecordBackpatch() above for a work around.
Parameters:
int imaker
This is the index returned from ISave::GetRefID(). that was used to save the pointer.
Prototype:
virtual void SetRootAddr(void *addr)=0;
Remarks:
This method is used internally.
Prototype:
virtual void* GetRootAddr()=0;
Remarks:
This method is used internally.
Prototype:
virtual TCHAR *GetDir(int which)=0;
Remarks:
Returns the name of various directories used by 3ds max. See List of Directory Names.
Prototype:
virtual FileIOType DoingWhat()=0;
Remarks:
Determines if we are loading a standard 3ds max file (.MAX) or a material library (.MAT).
Return Value:
One of the following values:
IOTYPE_MAX
IOTYPE_MATLIB
Prototype:
virtual INode *RootNode()=0;
Remarks:
Returns the root node to attach to when loading a node with no parent.
Prototype:
virtual ClassDesc* GetClassDesc(USHORT refID);
Remarks:
This method is available in release 3.0 and later only.
Returns a pointer to the ClassDesc corresponding to the specified reference ID in the ClassDirectory stream.
Parameters:
USHORT refID
The reference ID in the ClassDirectory stream.
Default Implementation:
{ return NULL; }
Prototype:
virtual DWORD GetFileSaveVersion();
Remarks:
This method is available in release 4.0 and later only.
This function is available to plug-ins when loading files. It returns a value describing the version of 3ds max used to save the file. The
value is composed of: LOWORD(value) = Build number. For example 41 for build #41. HIWORD(value) = MAX_RELEASE (defined as 3ds max release version * 1000), thus 3ds max version 4.0 is 4000
Return Value:
This function returns 0 if the file does not contain this value.
Default Implementation:
{ return 0; }