ISave Class Reference
 
 
 
ISave Class Reference

This reference page is linked to from the following overview topics: Loading and Saving Plug-in Data, Supporting Save to Previous, Serializing Controllers.


#include <ioapi.h>

Inheritance diagram for ISave:
InterfaceServer MaxHeapOperators

Class Description

See also:
Loading and Saving, Character Strings, Class ILoad, Class ClassDesc, Class ClassDirectory, Class Interface.

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:

Public Member Functions

virtual  ~ISave ()
virtual int  GetRefID (void *ptarg)=0
virtual void  BeginChunk (USHORT id)=0
virtual void  EndChunk ()=0
virtual int  CurChunkDepth ()=0
IOResult  WriteVoid (const void *buf, ULONG nbytes, ULONG *nwrit)
IOResult  WriteEnum (const void *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const char *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const wchar_t *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const int *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const unsigned int *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const INT64 *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const UINT64 *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const float *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const double *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const short *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const unsigned short *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const long *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const unsigned long *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const BYTE *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const bool *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Point2 *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Point3 *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Point4 *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const AColor *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Color *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Matrix2 *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Matrix3 *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Box2 *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Box3 *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const MNVert *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const TVPatch *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Face *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Class_ID *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const VertMove *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const FaceCreate *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const FaceRemap *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const FaceChange *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const FaceSmooth *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const UVVertSet *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const TVFace *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Interval *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const AngAxis *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Quat *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Ray *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const ScaleValue *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const RotationValue *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const FBox2 *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const HookPoint *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const PolyPt *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const bindShape *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const EPMapVert *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const EPMapPatch *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const EPMapUVVert *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const RandGenerator *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Interface_ID *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const BlockKeysClass *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Color24 *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Color48 *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const Color64 *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const POINT *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const WINDOWPLACEMENT *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const range *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const MaxSDK::AssetManagement::AssetId *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const ParamType2 *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const FloatChange *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const VertOffset *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const ParticleID *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const PreciseTimeValue *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const DeviceRect *buf, ULONG nbytes, ULONG *nwrit)
IOResult  Write (const IPoint2 *buf, ULONG nbytes, ULONG *nwrit)
virtual IOResult  WriteWString (const char *str)=0
virtual IOResult  WriteWString (const wchar_t *str)=0
virtual IOResult  WriteCString (const char *str)=0
virtual IOResult  WriteCString (const wchar_t *str)=0
virtual FileIOType  DoingWhat ()=0
virtual DWORD  SavingVersion () const
virtual USHORT  GetClassDescID (ReferenceMaker *rm)
virtual INT_PTR  Execute (int cmd, ULONG_PTR arg1=0, ULONG_PTR arg2=0, ULONG_PTR arg3=0)
virtual const MCHAR *  FileName ()
virtual IOResult  SaveAssetMetaData (const MaxSDK::AssetManagement::AssetId &assetId)
virtual bool  SaveAssetAsAssetIDGuid ()
virtual UINT  CodePage () const

Constructor & Destructor Documentation

virtual ~ISave ( ) [inline, virtual]
{};

Member Function Documentation

virtual int GetRefID ( void *  ptarg ) [pure virtual]
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.
Parameters:
ptarg The pointer to save.
Returns:
The id that may be saved to disk.
virtual void BeginChunk ( USHORT  id ) [pure virtual]
Remarks:
This method is used to begin a chunk. The ID passed need only be unique within the plug-ins data itself.
Parameters:
id The id for the chunk.
virtual void EndChunk ( ) [pure virtual]
Remarks:
This method is used to end a chunk, and back-patch the length.
virtual int CurChunkDepth ( ) [pure virtual]
Remarks:
This method is used internally for checking balanced BeginChunk/EndChunk.
IOResult WriteVoid ( const void *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
Remarks:
This method writes a block of bytes to the output stream.
Parameters:
buf The buffer to write.
nbytes The number of bytes to write.
nwrit The number of bytes actually written.
Returns:
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.
{return Write((void*)buf, nbytes, nwrit);}
IOResult WriteEnum ( const void *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{DbgAssert(nbytes == sizeof(int)); return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const char *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
        {
                DbgAssert( buf == NULL || strlen(buf) <= nbytes);
                return Write((void*)buf, nbytes, nwrit);
        }
IOResult Write ( const wchar_t *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
        {
                DbgAssert( buf == NULL || wcslen(buf) <= nbytes);
                return Write((void*)buf, nbytes, nwrit);
        }
IOResult Write ( const int *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const unsigned int *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const INT64 *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const UINT64 *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const float *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const double *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const short *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const unsigned short *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const long *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const unsigned long *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const BYTE *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const bool *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Point2 buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Point3 buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Point4 buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const AColor buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Color buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Matrix2 buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Matrix3 buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Box2 buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Box3 buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const MNVert buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const TVPatch buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Face buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Class_ID buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const VertMove buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const FaceCreate buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const FaceRemap buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const FaceChange buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const FaceSmooth buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const UVVertSet buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const TVFace buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Interval buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const AngAxis buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Quat buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Ray buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const ScaleValue buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const RotationValue buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const FBox2 buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const HookPoint buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const PolyPt buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const bindShape buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const EPMapVert *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const EPMapPatch *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const EPMapUVVert *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const RandGenerator buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Interface_ID buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const BlockKeysClass *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Color24 buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Color48 buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const Color64 buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const POINT *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const WINDOWPLACEMENT *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const range *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const MaxSDK::AssetManagement::AssetId buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const ParamType2 buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const FloatChange *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const VertOffset *  buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const ParticleID buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const PreciseTimeValue buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const DeviceRect buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
IOResult Write ( const IPoint2 buf,
ULONG  nbytes,
ULONG *  nwrit 
) [inline]
{return Write((void*)buf, nbytes, nwrit);}
virtual IOResult WriteWString ( const char *  str ) [pure virtual]
Remarks:
This method is used to write wide character strings.
Parameters:
str The string to write. The string must be ACP encoded.
Returns:
IO_OK - The write was acceptable - no errors.

IO_ERROR - This is returned if an error occurred.
virtual IOResult WriteWString ( const wchar_t *  str ) [pure virtual]
Remarks:
This method is used to write wide character strings.
Parameters:
str The string to write.
Returns:
IO_OK - The write was acceptable - no errors.

IO_ERROR - This is returned if an error occurred.
virtual IOResult WriteCString ( const char *  str ) [pure virtual]
Remarks:
This method is used to write single byte character strings.
Parameters:
str The string to write. The string must be ACP encoded.
Returns:
IO_OK - The write was acceptable - no errors.

IO_ERROR - This is returned if an error occurred.
virtual IOResult WriteCString ( const wchar_t *  str ) [pure virtual]
Remarks:
This method is used to write single byte character strings.
Parameters:
str The string to write.
Returns:
IO_OK - The write was acceptable - no errors.

IO_ERROR - This is returned if an error occurred.
virtual FileIOType DoingWhat ( ) [pure virtual]
Remarks:
Determines if we are saving a standard 3ds Max file (.MAX) or a material library (.MAT).
Returns:
One of the following values:

IOTYPE_MAX

IOTYPE_MATLIB
virtual DWORD SavingVersion ( ) const [inline, virtual]
Remarks:
This method returns a value to indicate the current version of the file being saved. It returns 0 for the current version, MAX_RELEASE_R12 for 3ds Max 2010, etc. Call this method to determine the format in which to save the data.
  • Adding a new chunk (unknown to the previous version) should be fine. Plug-ins should be written to skip over unknown chunks.
  • Removing a chunk is not fine. Never delete a chunk id. Plug-ins need to be prepared to save out the data corresponding to the old chunk id when this method returns the version of a previous 3ds Max release.
  • Changing the contents of an existent chunk is not fine, since it can break file compatibility. Add a new chunk to store the modified data structure, and keep the code that loads the old chunk. Be prepared to convert the old data to the new format if that makes sense.
See also:
GetSavingVersion(), 3dsMaxRelease
{ return  0; }
virtual USHORT GetClassDescID ( ReferenceMaker rm ) [inline, virtual]
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:
rm Points to the reference maker.
Default Implementation:
{ return 0xffff; }
virtual INT_PTR Execute ( int  cmd,
ULONG_PTR  arg1 = 0,
ULONG_PTR  arg2 = 0,
ULONG_PTR  arg3 = 0 
) [inline, virtual]
virtual const MCHAR* FileName ( ) [inline, virtual]
Remarks:
Returns the name of the scene file being saved.
{ return NULL; }
virtual IOResult SaveAssetMetaData ( const MaxSDK::AssetManagement::AssetId assetId ) [inline, virtual]
Remarks:
This method is used by Asset Manager to save to the scene file the asset meta data.
Parameters:
assetId The id for the asset.
Returns:
A return value of IO_ERROR indicates an error occurred, otherwise IO_OK.
{ return IO_OK; }
virtual bool SaveAssetAsAssetIDGuid ( ) [inline, virtual]
Remarks:
This method is used to tell when to store an asset as a guid rather than as the asset filename.
Returns:
A return value of true indicates to store eassets as guids, otherwise as the asset filename.
{ return false; }
virtual UINT CodePage ( ) const [inline, virtual]