#include <c4d_file.h>

Detailed Description

Hyper files are used to save plugin data that cannot be stored in a BaseContainer.
Cinema 4D creates it and pass it to dedicated Load and Save overrides when needed (see NodeData and CustomDataTypeClass).
Access to the hyper file's data is like a FIFO (first in, first out) buffer; the values must be written and read in the same order.

Note: Has to be created with Alloc() and destroyed with Free(). Use AutoAlloc to automate the allocation and destruction based on scope.

Private Member Functions
	HyperFile ()

	~HyperFile ()

Alloc/Free
static HyperFile *	Alloc (void)

static void	Free (HyperFile *&fl)

Open/Close
Bool	Open (Int32 ident, const Filename &filename, FILEOPEN mode, FILEDIALOG error_dialog)

Bool	Close ()

Read
Bool	ReadChar (Char *v)

Bool	ReadUChar (UChar *v)

Bool	ReadInt16 (Int16 *v)

Bool	ReadUInt16 (UInt16 *v)

Bool	ReadInt32 (Int32 *v)

Bool	ReadUInt32 (UInt32 *v)

Bool	ReadInt64 (Int64 *v)

Bool	ReadUInt64 (UInt64 *v)

Bool	ReadFloat (Float *v)

Bool	ReadFloat32 (Float32 *v)

Bool	ReadFloat64 (Float64 *v)

Bool	ReadBool (Bool *v)

Bool	ReadTime (BaseTime *v)

Bool	ReadVector (Vector *v)

Bool	ReadVector32 (Vector32 *v)

Bool	ReadVector64 (Vector64 *v)

Bool	ReadMatrix (Matrix *v)

Bool	ReadMatrix32 (Matrix32 *v)

Bool	ReadMatrix64 (Matrix64 *v)

Bool	ReadString (maxon::String *v)

Bool	ReadFilename (Filename *v)

Bool	ReadImage (BaseBitmap *v)

Bool	ReadGeData (GeData *v)

Bool	ReadContainer (BaseContainer *v, Bool flush)

Bool	ReadMemory (void *data, Int size)

Bool	ReadChannelConvert (GeListNode *node, Int32 link_id)

Bool	ReadArray (void *data, HYPERFILEARRAY type, Int32 structure_increment, Int32 count)

Bool	ReadUuid (C4DUuid *v)

Write
Bool	WriteChar (Char v)

Bool	WriteUChar (UChar v)

Bool	WriteInt16 (Int16 v)

Bool	WriteUInt16 (UInt16 v)

Bool	WriteInt32 (Int32 v)

Bool	WriteUInt32 (UInt32 v)

Bool	WriteInt64 (Int64 v)

Bool	WriteUInt64 (UInt64 v)

Bool	WriteFloat (Float v)

Bool	WriteFloat32 (Float32 v)

Bool	WriteFloat64 (Float64 v)

Bool	WriteBool (Bool v)

Bool	WriteTime (const BaseTime &v)

Bool	WriteVector (const Vector &v)

Bool	WriteVector32 (const Vector32 &v)

Bool	WriteVector64 (const Vector64 &v)

Bool	WriteMatrix (const Matrix &v)

Bool	WriteMatrix32 (const Matrix32 &v)

Bool	WriteMatrix64 (const Matrix64 &v)

Bool	WriteString (const maxon::String &v)

Bool	WriteFilename (const Filename &v)

Bool	WriteImage (BaseBitmap bmp, Int32 format, BaseContainer data, SAVEBIT savebits=SAVEBIT::ALPHA)

Bool	WriteGeData (const GeData &v)

Bool	WriteContainer (const BaseContainer &v)

Bool	WriteMemory (const void *data, Int count)

Bool	WriteArray (const void *data, HYPERFILEARRAY datatype, Int32 structure_increment, Int32 count)

Bool	WriteUuid (const C4DUuid &v)

Error
FILEERROR	GetError () const

void	SetError (FILEERROR err)

HyperFile Value
Bool	ReadValueHeader (HYPERFILEVALUE *h)

Bool	SkipValue (HYPERFILEVALUE h)

Chunk Start/End
Bool	WriteChunkStart (Int32 id, Int32 level)

Bool	WriteChunkEnd (void)

Bool	ReadChunkStart (Int32 id, Int32 level)

Bool	ReadChunkEnd (void)

Bool	SkipToEndChunk (void)

File Version
Int32	GetFileVersion () const

void	SetFileVersion (Int32 val)

Miscellaneous
BaseDocument *	GetDocument () const

LOCATION	GetLocation (void) const

SCENEFILTER	GetFilterFlags () const

Constructor & Destructor Documentation

◆ HyperFile()

HyperFile ( )

private

◆ ~HyperFile()

~HyperFile ( )

private

Member Function Documentation

◆ Alloc()

static HyperFile* Alloc ( void )

static

Allocates a hyper file. Destroy the allocated hyper file with Free(). Use AutoAlloc to automate the allocation and destruction based on scope.

Returns: The allocated hyper file, or nullptr if the allocation failed.

◆ Free()

static void Free ( HyperFile *& fl )

static

Destructs hyper files allocated with Alloc(). Use AutoAlloc to automate the allocation and destruction based on scope.

Parameters

[in,out] fl The hyper file to destruct. If the pointer is nullptr nothing happens. The pointer is assigned nullptr afterwards.

◆ Open()

Bool Open	(	Int32	ident,
		const Filename &	filename,
		FILEOPEN	mode,
		FILEDIALOG	error_dialog
	)

Opens the hyper file.

Parameters

[in]	ident	The file identification.
[in]	filename	The name of the file to open.
[in]	mode	The file mode: FILEOPEN
[in]	error_dialog	The file error dialog: FILEDIALOG

Returns: true if the hyper file could be opened, otherwise false.

◆ Close()

Bool Close ( )

Closes the hyper file.

Returns: true if the hyper file could be closed, otherwise false.

◆ ReadChar()

Bool ReadChar ( Char * v )

Reads a Char value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadUChar()

Bool ReadUChar ( UChar * v )

Reads a UChar value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadInt16()

Bool ReadInt16 ( Int16 * v )

Reads a Int16 value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadUInt16()

Bool ReadUInt16 ( UInt16 * v )

Reads a UInt16 value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadInt32()

Bool ReadInt32 ( Int32 * v )

Reads a Int32 value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadUInt32()

Bool ReadUInt32 ( UInt32 * v )

Reads a UInt32 value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadInt64()

Bool ReadInt64 ( Int64 * v )

Reads a Int64 value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadUInt64()

Bool ReadUInt64 ( UInt64 * v )

Reads a UInt64 value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadFloat()

Bool ReadFloat ( Float * v )

Reads a Float value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadFloat32()

Bool ReadFloat32 ( Float32 * v )

Reads a Float32 value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadFloat64()

Bool ReadFloat64 ( Float64 * v )

Reads a Float64 value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadBool()

Bool ReadBool ( Bool * v )

Reads a Bool value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadTime()

Bool ReadTime ( BaseTime * v )

Reads a BaseTime value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadVector()

Bool ReadVector ( Vector * v )

Reads a Vector value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadVector32()

Bool ReadVector32 ( Vector32 * v )

Reads a Vector32 value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadVector64()

Bool ReadVector64 ( Vector64 * v )

Reads a Vector64 value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadMatrix()

Bool ReadMatrix ( Matrix * v )

Reads a Matrix value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadMatrix32()

Bool ReadMatrix32 ( Matrix32 * v )

Reads a Matrix32 value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadMatrix64()

Bool ReadMatrix64 ( Matrix64 * v )

Reads a Matrix64 value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadString()

Bool ReadString ( maxon::String * v )

Reads a String value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadFilename()

Bool ReadFilename ( Filename * v )

Reads a Filename value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadImage()

Bool ReadImage ( BaseBitmap * v )

Reads a BaseBitmap value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadGeData()

Bool ReadGeData ( GeData * v )

Reads a GeData value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ ReadContainer()

Bool ReadContainer	(	BaseContainer *	v,
		Bool	flush
	)

Reads a container from the hyper file.

Parameters

[out]	v	Assigned the value read from the hyper file.
[in]	flush	Specify if the container should be cleared before reading the new values. Passing false will merge the container with the one read from the file.

Returns: Success of reading the container.

◆ ReadMemory()

Bool ReadMemory	(	void **	data,
		Int *	size
	)

Reads a block of memory from the hyper file.

Note: Only use when really needed. Be aware that the byte sequences will not be platform independent. Example:
Int32 size;

void* data = nullptr;

Bool ok = ReadMemory(&data, &size);

DeleteMem(data);

HyperFile::ReadMemory
Bool ReadMemory(void **data, Int *size)

size
Py_ssize_t size
Definition: bytesobject.h:86

Bool
maxon::Bool Bool
Definition: ge_sys_math.h:55

Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:60

maxon::DeleteMem
void DeleteMem(T *&p)
Definition: defaultallocator.h:257

Parameters

[out]	data	A pointer to the start of the memory block to read.
[out]	size	Assigned the byte size of the memory data read.

Returns: Success of reading the memory block.

◆ ReadChannelConvert()

Bool ReadChannelConvert	(	GeListNode *	node,
		Int32	link_id
	)

Deprecated.

◆ ReadArray()

Bool ReadArray	(	void *	data,
		HYPERFILEARRAY	type,
		Int32	structure_increment,
		Int32	count
	)

Reads an array of the specified type from the hyper file.

Parameters

[out]	data	A pointer to an array to be filled. The caller owns the pointed array.
[in]	type	The data type: HYPERFILEARRAY
[in]	structure_increment	The size of the data type (sizeof()).
[in]	count	The umber of elements in data.

Returns: Success of reading the array.

◆ ReadUuid()

Bool ReadUuid ( C4DUuid * v )

Reads a C4DUuid value from the hyper file.

Parameters

[out] v Assigned the value read from the hyper file.

Returns: Success of reading the value.

◆ WriteChar()

Bool WriteChar ( Char v )

Writes a Char value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteUChar()

Bool WriteUChar ( UChar v )

Writes a UChar value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteInt16()

Bool WriteInt16 ( Int16 v )

Writes a Int16 value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteUInt16()

Bool WriteUInt16 ( UInt16 v )

Writes a UInt16 value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteInt32()

Bool WriteInt32 ( Int32 v )

Writes a Int32 value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteUInt32()

Bool WriteUInt32 ( UInt32 v )

Writes a UInt32 value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteInt64()

Bool WriteInt64 ( Int64 v )

Writes a Int64 value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteUInt64()

Bool WriteUInt64 ( UInt64 v )

Writes a UInt64 value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteFloat()

Bool WriteFloat ( Float v )

Writes a Float value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteFloat32()

Bool WriteFloat32 ( Float32 v )

Writes a Float32 value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteFloat64()

Bool WriteFloat64 ( Float64 v )

Writes a Float64 value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteBool()

Bool WriteBool ( Bool v )

Writes a Bool value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteTime()

Bool WriteTime ( const BaseTime & v )

Writes a BaseTime value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteVector()

Bool WriteVector ( const Vector & v )

Writes a Vector value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteVector32()

Bool WriteVector32 ( const Vector32 & v )

Writes a Vector32 value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteVector64()

Bool WriteVector64 ( const Vector64 & v )

Writes a Vector64 value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteMatrix()

Bool WriteMatrix ( const Matrix & v )

Writes a Matrix value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteMatrix32()

Bool WriteMatrix32 ( const Matrix32 & v )

Writes a Matrix32 value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteMatrix64()

Bool WriteMatrix64 ( const Matrix64 & v )

Writes a Matrix64 value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteString()

Bool WriteString ( const maxon::String & v )

Writes a String value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteFilename()

Bool WriteFilename ( const Filename & v )

Writes a Filename value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteImage()

Bool WriteImage	(	BaseBitmap *	bmp,
		Int32	format,
		BaseContainer *	data,
		SAVEBIT	savebits = `SAVEBIT::ALPHA`
	)

Writes an image to the hyper file.

Parameters

[in]	bmp	The bitmap to write to the hyperfile. The caller owns the pointed bitmap.
[in]	format	The image format: FILTER
[in]	data	A container with additional format settings, or nullptr.
[in]	savebits	The save bits: SAVEBIT

Returns: Success of writing the image.

◆ WriteGeData()

Bool WriteGeData ( const GeData & v )

Writes a Char value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ WriteContainer()

Bool WriteContainer ( const BaseContainer & v )

Writes a container to the hyper file.

Parameters

[in] v The container to write to the hyper file.

Returns: Success of writing the container.

◆ WriteMemory()

Bool WriteMemory	(	const void *	data,
		Int	count
	)

Writes a block of memory to the hyper file.

Note: Only use when really needed. Be aware that the byte sequences will not be platform independent.

Parameters

[in]	data	The start of the memory block to write to the hyper file.
[in]	count	The size in bytes of the memory data to write.

Returns: Success of writing the memory block.

◆ WriteArray()

Bool WriteArray	(	const void *	data,
		HYPERFILEARRAY	datatype,
		Int32	structure_increment,
		Int32	count
	)

Writes an array of the specified datatype to the hyper file.

Parameters

[in]	data	The pointer to the array. The caller owns the pointed array.
[in]	datatype	The array data type: HYPERFILEARRAY
[in]	structure_increment	Size of the data type (sizeof()).
[in]	count	The number of elements in data.

Returns: Success of writing the array.

◆ WriteUuid()

Bool WriteUuid ( const C4DUuid & v )

Writes a C4DUuid value to the hyper file.

Parameters

[in] v The value to write to the hyper file.

Returns: Success of writing the value.

◆ GetError()

FILEERROR GetError ( ) const

Gets the error from the last hyper file operation.

Returns: The error: FILEERROR

◆ SetError()

void SetError ( FILEERROR err )

Sets the error for the hyper file.

Parameters

[in] err The error to set: FILEERROR

◆ ReadValueHeader()

Bool ReadValueHeader ( HYPERFILEVALUE * h )

Reads the value header from the hyper file.
This is only necessary in combination with loops.
For example:

static Bool ReadSettings(BaseObject *op, HyperFile *hf, Int32 level)
{
  Int32 id, level, v;
  String test;
  HYPERFILEVALUE h;
  while (hf->ReadValueHeader(&h) && h==HYPERFILEVALUE::START)
  {
    if (!hf->ReadChunkStart(&id, &level))
      return false;
 
    if (id==2)
    {
      hf->ReadInt32(&v);
      hf->ReadInt32(&v);
    }
    else if (id==3)
    {
      hf->ReadInt32(&v);
      hf->ReadInt32(&v);
      hf->ReadInt32(&v);
    }
    hf->SkipToEndChunk(); // Never forget this at the end
    if (id==0)
      break; // Chunk ID 0 is end chunk
  }
 
  hf->ReadString(test);
 
  return true;
}

Parameters

[in] h A pointer to a HYPERFILEVALUE to take the header value: HYPERFILEVALUE

Returns: true if the header was read successfully, otherwise false.

◆ SkipValue()

Bool SkipValue ( HYPERFILEVALUE h )

Skips a given type of value.

Parameters

[in] h The hyper file value to skip: HYPERFILEVALUE

Returns: true if the value was of the given header type and it was skipped, otherwise false.

◆ WriteChunkStart()

Bool WriteChunkStart	(	Int32	id,
		Int32	level
	)

Writes a chunk marker into the file indicating the beginning of a new chunk of data.

Parameters

[in]	id	The ID for the chunk.
[in]	level	To write additional information, increase this level to save/read new values.

Returns: true if the chunk identification was written successfully, otherwise false.

◆ WriteChunkEnd()

Bool WriteChunkEnd ( void )

Writes a chunk ending marker into the hyper file.

Returns: true if the chunk end was written successfully, otherwise false.

◆ ReadChunkStart()

Bool ReadChunkStart	(	Int32 *	id,
		Int32 *	level
	)

Reads a chunks identification from the hyper file.

Parameters

[out]	id	Assigned the chunk ID.
[out]	level	Assigned the chunk level.

Returns: true if the chunk start was read successfully, otherwise false.

◆ ReadChunkEnd()

Bool ReadChunkEnd ( void )

Reads a chunk end marker from the hyper file.

Returns: true if the chunk end was read successfully, otherwise false.

◆ SkipToEndChunk()

Bool SkipToEndChunk ( void )

Moves the file pointer to the end of the chunk.

Note: Should always be called after having finished reading values from the current chunk.

Returns: true if the end of the chunk was found and skipped to, otherwise false.

◆ GetFileVersion()

Int32 GetFileVersion ( ) const

Gets the version of Cinema 4D that wrote the file. (Only valid while reading a Cinema 4D scene, object, material etc.)

Returns: The file version.

◆ SetFileVersion()

void SetFileVersion ( Int32 val )

Private.

◆ GetDocument()

BaseDocument* GetDocument ( ) const

Gets the active document for the hyper file operation.
Can be nullptr, for instance when saving layouts.

Returns: The document for the hyper file operation. Cinema 4D owns the pointed document.

◆ GetLocation()

LOCATION GetLocation ( void ) const

Gets the hyper file location.

Returns: The hyper file location: LOCATION

◆ GetFilterFlags()

SCENEFILTER GetFilterFlags ( ) const

Gets the filter flags, the value is valid only during a Load or a Merge.

Returns: The filter flags: SCENEFILTER

Detailed Description

Private Member Functions

Alloc/Free

Open/Close

Read

Write

Error

HyperFile Value

Chunk Start/End

File Version

Miscellaneous

Constructor & Destructor Documentation

◆ HyperFile()

◆ ~HyperFile()

Member Function Documentation

◆ Alloc()

◆ Free()

◆ Open()

◆ Close()

◆ ReadChar()

◆ ReadUChar()

◆ ReadInt16()

◆ ReadUInt16()

◆ ReadInt32()

◆ ReadUInt32()

◆ ReadInt64()

◆ ReadUInt64()

◆ ReadFloat()

◆ ReadFloat32()

◆ ReadFloat64()

◆ ReadBool()

◆ ReadTime()

◆ ReadVector()

◆ ReadVector32()

◆ ReadVector64()

◆ ReadMatrix()

◆ ReadMatrix32()

◆ ReadMatrix64()

◆ ReadString()

◆ ReadFilename()

◆ ReadImage()

◆ ReadGeData()

◆ ReadContainer()

◆ ReadMemory()

◆ ReadChannelConvert()

◆ ReadArray()

◆ ReadUuid()

◆ WriteChar()

◆ WriteUChar()

◆ WriteInt16()

◆ WriteUInt16()

◆ WriteInt32()

◆ WriteUInt32()

◆ WriteInt64()

◆ WriteUInt64()

◆ WriteFloat()

◆ WriteFloat32()

◆ WriteFloat64()

◆ WriteBool()

◆ WriteTime()

◆ WriteVector()

◆ WriteVector32()

◆ WriteVector64()

◆ WriteMatrix()

◆ WriteMatrix32()

◆ WriteMatrix64()

◆ WriteString()

◆ WriteFilename()

◆ WriteImage()

◆ WriteGeData()

◆ WriteContainer()

◆ WriteMemory()

◆ WriteArray()

◆ WriteUuid()

◆ GetError()

◆ SetError()

◆ ReadValueHeader()

◆ SkipValue()

◆ WriteChunkStart()

◆ WriteChunkEnd()