Class ISave
See Also: Loading and Saving, Character Strings, Class ILoad, Class ClassDesc, Class ClassDirectory, Class Interface.
class ISave : public InterfaceServer
Description:
This class provides methods to save data to disk.
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.
Note about member alignment: Please make sure that when you save data from your plugin you save individual data members using a chunk ID instead of saving the image of a class. Saving (and loading) a class image puts you at risk of running into member alignment problems and as such could potentially corrupt saved files. File IO would be put further at risk when you keep Intel’s IA-64 architecture in mind which depends on member alignment. What you should not do is outlined in the following example when loading a class image; iload->Read(&myclass, sizeof(MyClass), &ab);
Once you change the class in such a way that it affects the data size you run the risk of having to support different versions, file IO incompatibility, and member alignment issues.
The following global function is not part of this class but is available for use:
Function:
DWORD GetSavingVersion();
Remarks:
This function is available in release 3.0 and later only.
This function is reserved for future use as of 3ds max 4.
This global function is used to find out if we are saving an old version .3ds max file. If this returns 0, then either we are not in a save or we are saving the current version. If it returns non-zero, it is the max release number being saved, multiplied by 1000. Thus, when saving 3ds max R2 files, it will return 2000. This function can be used in NumRefs() and GetRef() to make an objects references appear as they did in the old 3ds max version.
Methods:
All methods of this class are implemented by the system.
Prototype:
virtual void BeginChunk(USHORT id) =0;
Remarks:
This method is used to begin a chunk. The ID passed need only be unique within the plug-ins data itself.
Parameters:
USHORT id
The id for the chunk.
Prototype:
virtual void EndChunk()=0;
Remarks:
This method is used to end a chunk, and back-patch the length.
Prototype:
virtual int CurChunkDepth()=0;
Remarks:
This method is used internally for checking balanced BeginChunk/EndChunk.
Prototype:
virtual IOResult Write(const void *buf, ULONG nbytes, ULONG *nwrit)=0;
Remarks:
This method writes a block of bytes to the output stream.
Parameters:
const void *buf
The buffer to write.
ULONG nbytes
The number of bytes to write.
ULONG *nwrit
The number of bytes actually written.
Return Value:
IO_OK - The write was acceptable - no errors.
IO_ERROR - This is returned if an error occurred. Note that the plug-in should not put up a message box if a write error occurs. It should simply return the error status. This prevents a overabundance of messages from appearing.
Prototype:
virtual IOResult WriteWString(const char *str)=0;
Remarks:
This method is used to write wide character strings.
Parameters:
const char *str
The string to write.
Return Value:
IO_OK - The write was acceptable - no errors.
IO_ERROR - This is returned if an error occurred.
Prototype:
virtual IOResult WriteWString(const wchar_t *str)=0;
Remarks:
This method is used to write wide character strings.
Parameters:
const wchar_t *str
The string to write.
Return Value:
IO_OK - The write was acceptable - no errors.
IO_ERROR - This is returned if an error occurred.
Prototype:
virtual IOResult WriteCString(const char *str)=0;
Remarks:
This method is used to write single byte character strings.
Parameters:
const char *str
The string to write.
Return Value:
IO_OK - The write was acceptable - no errors.
IO_ERROR - This is returned if an error occurred.
Prototype:
virtual IOResult WriteCString(const wchar_t *str)=0;
Remarks:
This method is used to write single byte character strings.
Parameters:
const wchar_t *str
The string to write.
Return Value:
IO_OK - The write was acceptable - no errors.
IO_ERROR - This is returned if an error occurred.
Prototype:
virtual int GetRefID(void *ptarg)=0;
Remarks:
This method is not normally used because the reference hierarchy is saved automatically. In certain cases however this method is quite useful. This method is used in saving a pointer to some object (or a table of pointers). This is a pointer to one of the objects that the scene saves with the reference hierarchy, but it is not a pointer that itself is a reference. For example the Ring Array plug-in uses this when it saves its table of nodes in the ring array. To save these pointers you can call this method and it will return an ID that you can save to disk. Then when you load this ID from disk you can call ILoad::RecordBackpatch() and get back a pointer.
Parameters:
void *ptarg
The pointer to save.
Return Value:
The id that may be saved to disk.
Prototype:
virtual FileIOType DoingWhat()=0;
Remarks:
Determines if we are saving a standard 3ds max file (.MAX) or a material library (.MAT).
Return Value:
One of the following values:
IOTYPE_MAX
IOTYPE_MATLIB
Prototype:
virtual DWORD SavingVersion();
Remarks:
This method is available in release 3.0 and later only.
This function is reserved for future use as of 3ds max 4.
This version returns a value to indicate the current version of the file being saved. It returns 0 0 for the current version, 2000 for version 2.0, 3000 for 3.0, etc. This basically duplicates the global function GetSavingVersion(). In general, Save routines need not to be concerned that they are saving chunks types that are unknown to the old version, because they will be skipped on load, but there may be cases where the Save routine needs to do things differently.
Default Implementation:
{ return 0; }
Prototype:
virtual USHORT GetClassDescID(ReferenceMaker* rm);
Remarks:
This method is available in release 3.0 and later only.
This method returns a load reference ID for the given Reference Maker's ClassDesc object in the ClassDirectory stream.
Parameters:
ReferenceMaker* rm
Points to the reference maker.
Default Implementation:
{ return 0xffff; }