Space-Project/dependencies/physx-4.1/include/common/PxSerialFramework.h
2021-01-16 17:11:39 +01:00

400 lines
14 KiB
C++

//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
// * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
// * Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the
// documentation and/or other materials provided with the distribution.
// * Neither the name of NVIDIA CORPORATION nor the names of its
// contributors may be used to endorse or promote products derived
// from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Copyright (c) 2008-2019 NVIDIA Corporation. All rights reserved.
// Copyright (c) 2004-2008 AGEIA Technologies, Inc. All rights reserved.
// Copyright (c) 2001-2004 NovodeX AG. All rights reserved.
#ifndef PX_PHYSICS_COMMON_NX_SERIAL_FRAMEWORK
#define PX_PHYSICS_COMMON_NX_SERIAL_FRAMEWORK
/** \addtogroup common
@{
*/
#include "common/PxPhysXCommonConfig.h"
#if !PX_DOXYGEN
namespace physx
{
#endif
typedef PxU16 PxType;
class PxBase;
class PxSerializationContext;
class PxRepXSerializer;
class PxSerializer;
class PxPhysics;
//! Default serialization alignment
#define PX_SERIAL_ALIGN 16
//! Serialized input data must be aligned to this value
#define PX_SERIAL_FILE_ALIGN 128
//! PxSerialObjectId value for objects that do not have an ID
#define PX_SERIAL_OBJECT_ID_INVALID 0
//! ID type for PxBase objects in a PxCollection
typedef PxU64 PxSerialObjectId;
//! Bit to mark pointer type references, @see PxDeserializationContext
#define PX_SERIAL_REF_KIND_PTR_TYPE_BIT (1u<<31)
//! Reference kind value for PxBase objects
#define PX_SERIAL_REF_KIND_PXBASE (0 | PX_SERIAL_REF_KIND_PTR_TYPE_BIT)
//! Reference kind value for material indices
#define PX_SERIAL_REF_KIND_MATERIAL_IDX (1)
//! Used to fix multi-byte characters warning from gcc for situations like: PxU32 foo = 'CCTS';
#define PX_MAKE_FOURCC(a, b, c, d) ( (a) | ((b)<<8) | ((c)<<16) | ((d)<<24) )
/**
\brief Callback class used to process PxBase objects.
@see PxSerializer::requires
*/
class PxProcessPxBaseCallback
{
public:
virtual ~PxProcessPxBaseCallback() {}
virtual void process(PxBase&) = 0;
};
/**
\brief Binary serialization context class.
This class is used to register reference values and write object
and object extra data during serialization.
It is mainly used by the serialization framework. Except for custom
serializable types, users should not have to worry about it.
@see PxDeserializationContext
*/
class PxSerializationContext
{
public:
/**
\brief Registers a reference value corresponding to a PxBase object.
This method is assumed to be called in the implementation of PxSerializer::registerReferences for serialized
references that need to be resolved on deserialization.
A reference needs to be associated with exactly one PxBase object in either the collection or the
external references collection.
Different kinds of references are supported and need to be specified. In the most common case
(PX_SERIAL_REF_KIND_PXBASE) the PxBase object matches the reference value (which is the pointer
to the PxBase object). Integer references maybe registered as well (used for internal material
indices with PX_SERIAL_REF_KIND_MATERIAL_IDX). Other kinds could be added with the restriction that
for pointer types the kind value needs to be marked with the PX_SERIAL_REF_KIND_PTR_TYPE_BIT.
\param[in] base PxBase object associated with the reference
\param[in] kind What kind of reference this is (PX_SERIAL_REF_KIND_PXBASE, PX_SERIAL_REF_KIND_MATERIAL_IDX or custom kind)
\param[in] reference Value of reference
@see PxDeserializationContext::resolveReference, PX_SERIAL_REF_KIND_PXBASE, PX_SERIAL_REF_KIND_MATERIAL_IDX, PxSerializer::registerReferences
*/
virtual void registerReference(PxBase& base, PxU32 kind, size_t reference) = 0;
/**
\brief Returns the collection that is being serialized.
*/
virtual const PxCollection& getCollection() const = 0;
/**
\brief Serializes object data and object extra data.
This function is assumed to be called within the implementation of PxSerializer::exportData and PxSerializer::exportExtraData.
@see PxSerializer::exportData, PxSerializer::exportExtraData, PxSerializer::createObject, PxDeserializationContext::readExtraData
*/
virtual void writeData(const void* data, PxU32 size) = 0;
/**
\brief Aligns the serialized data.
This function is assumed to be called within the implementation of PxSerializer::exportData and PxSerializer::exportExtraData.
@see PxSerializer::exportData, PxSerializer::exportExtraData, PxDeserializationContext::alignExtraData
*/
virtual void alignData(PxU32 alignment = PX_SERIAL_ALIGN) = 0;
/**
\brief Helper function to write a name to the extraData if serialization is configured to save names.
This function is assumed to be called within the implementation of PxSerializer::exportExtraData.
@see PxSerialization::serializeCollectionToBinary, PxDeserializationContext::readName
*/
virtual void writeName(const char* name) = 0;
protected:
PxSerializationContext() {}
virtual ~PxSerializationContext() {}
};
/**
\brief Binary deserialization context class.
This class is used to resolve references and access extra data during deserialization.
It is mainly used by the serialization framework. Except for custom
serializable types, users should not have to worry about it.
@see PxSerializationContext
*/
class PxDeserializationContext
{
public:
/**
\brief Retrieves a pointer to a deserialized PxBase object given a corresponding deserialized reference value
This method is assumed to be called in the implementation of PxSerializer::createObject in order
to update reference values on deserialization.
To update a PxBase reference the corresponding deserialized pointer value needs to be provided in order to retrieve
the location of the corresponding deserialized PxBase object. (PxDeserializationContext::translatePxBase simplifies
this common case).
For other kinds of references the reverence values need to be updated by deduction given the corresponding PxBase instance.
\param[in] kind What kind of reference this is (PX_SERIAL_REF_KIND_PXBASE, PX_SERIAL_REF_KIND_MATERIAL_IDX or custom kind)
\param[in] reference Deserialized reference value
\return PxBase object associated with the reference value
@see PxSerializationContext::registerReference, PX_SERIAL_REF_KIND_PXBASE, PX_SERIAL_REF_KIND_MATERIAL_IDX, translatePxBase
*/
virtual PxBase* resolveReference(PxU32 kind, size_t reference) const = 0;
/**
\brief Helper function to update PxBase pointer on deserialization
@see resolveReference, PX_SERIAL_REF_KIND_PXBASE
*/
template<typename T>
void translatePxBase(T*& base) { if (base) { base = static_cast<T*>(resolveReference(PX_SERIAL_REF_KIND_PXBASE, size_t(base))); } }
/**
\brief Helper function to read a name from the extra data during deserialization.
This function is assumed to be called within the implementation of PxSerializer::createObject.
@see PxSerializationContext::writeName
*/
PX_INLINE void readName(const char*& name)
{
PxU32 len = *reinterpret_cast<PxU32*>(mExtraDataAddress);
mExtraDataAddress += sizeof(len);
name = len ? reinterpret_cast<const char*>(mExtraDataAddress) : NULL;
mExtraDataAddress += len;
}
/**
\brief Function to read extra data during deserialization.
This function is assumed to be called within the implementation of PxSerializer::createObject.
@see PxSerializationContext::writeData, PxSerializer::createObject
*/
template<typename T>
PX_INLINE T* readExtraData(PxU32 count=1)
{
T* data = reinterpret_cast<T*>(mExtraDataAddress);
mExtraDataAddress += sizeof(T)*count;
return data;
}
/**
\brief Function to read extra data during deserialization optionally aligning the extra data stream before reading.
This function is assumed to be called within the implementation of PxSerializer::createObject.
@see PxSerializationContext::writeData, PxDeserializationContext::alignExtraData, PxSerializer::createObject
*/
template<typename T, PxU32 alignment>
PX_INLINE T* readExtraData(PxU32 count=1)
{
alignExtraData(alignment);
return readExtraData<T>(count);
}
/**
\brief Function to align the extra data stream to a power of 2 alignment
This function is assumed to be called within the implementation of PxSerializer::createObject.
@see PxSerializationContext::alignData, PxSerializer::createObject
*/
PX_INLINE void alignExtraData(PxU32 alignment = PX_SERIAL_ALIGN)
{
size_t addr = reinterpret_cast<size_t>(mExtraDataAddress);
addr = (addr+alignment-1)&~size_t(alignment-1);
mExtraDataAddress = reinterpret_cast<PxU8*>(addr);
}
protected:
PxDeserializationContext() {}
virtual ~PxDeserializationContext() {}
PxU8* mExtraDataAddress;
};
/**
\brief Callback type for exporting binary meta data for a serializable type.
@see PxSerializationRegistry::registerBinaryMetaDataCallback
\param stream Stream to store binary meta data.
*/
typedef void (*PxBinaryMetaDataCallback)(PxOutputStream& stream);
/**
\brief Class serving as a registry for XML (RepX) and binary serializable types.
In order to serialize and deserialize objects the application needs
to maintain an instance of this class. It can be created with
PxSerialization::createSerializationRegistry() and released with
PxSerializationRegistry::release().
@see PxSerialization::createSerializationRegistry
*/
class PxSerializationRegistry
{
public:
/************************************************************************************************/
/** @name Binary Serialization Functionality
*/
//@{
/**
\brief Register a serializer for a concrete type
\param type PxConcreteType corresponding to the serializer
\param serializer The PxSerializer to be registered
@see PxConcreteType, PxSerializer, PxSerializationRegistry::unregisterSerializer
*/
virtual void registerSerializer(PxType type, PxSerializer& serializer) = 0;
/**
\brief Unregister a serializer for a concrete type, and retrieves the corresponding serializer object.
\param type PxConcreteType for which the serializer should be unregistered
\return Unregistered serializer corresponding to type, NULL for types for which no serializer has been registered.
@see PxConcreteType, PxSerializationRegistry::registerSerializer, PxSerializationRegistry::release
*/
virtual PxSerializer* unregisterSerializer(PxType type) = 0;
/**
\brief Register binary meta data callback
The callback is executed when calling PxSerialization::dumpBinaryMetaData.
\param callback PxBinaryMetaDataCallback to be registered.
@see PxBinaryMetaDataCallback, PxSerialization::dumpBinaryMetaData
*/
virtual void registerBinaryMetaDataCallback(PxBinaryMetaDataCallback callback) = 0;
/**
\brief Returns PxSerializer corresponding to type
\param type PxConcreteType of the serializer requested.
\return Registered PxSerializer object corresponding to type
@see PxConcreteType
*/
virtual const PxSerializer* getSerializer(PxType type) const = 0;
//@}
/************************************************************************************************/
/** @name RepX (XML) Serialization Functionality
*/
//@{
/**
\brief Register a RepX serializer for a concrete type
\param type PxConcreteType corresponding to the RepX serializer
\param serializer The PxRepXSerializer to be registered
@see PxConcreteType, PxRepXSerializer
*/
virtual void registerRepXSerializer(PxType type, PxRepXSerializer& serializer) = 0;
/**
\brief Unregister a RepX serializer for a concrete type, and retrieves the corresponding serializer object.
\param type PxConcreteType for which the RepX serializer should be unregistered
\return Unregistered PxRepxSerializer corresponding to type, NULL for types for which no RepX serializer has been registered.
@see PxConcreteType, PxSerializationRegistry::registerRepXSerializer, PxSerializationRegistry::release
*/
virtual PxRepXSerializer* unregisterRepXSerializer(PxType type) = 0;
/**
\brief Returns RepX serializer given the corresponding type name
\param typeName Name of the type
\return Registered PxRepXSerializer object corresponding to type name
@see PxRepXSerializer, PxTypeInfo, PX_DEFINE_TYPEINFO
*/
virtual PxRepXSerializer* getRepXSerializer(const char* typeName) const = 0;
//@}
/************************************************************************************************/
/**
\brief Releases PxSerializationRegistry instance.
This unregisters all PhysX and PhysXExtension serializers. Make sure to unregister all custom type
serializers before releasing the PxSerializationRegistry.
@see PxSerializationRegistry::unregisterSerializer, PxSerializationRegistry::unregisterRepXSerializer
*/
virtual void release() = 0;
protected:
virtual ~PxSerializationRegistry(){}
};
#if !PX_DOXYGEN
} // namespace physx
#endif
/** @} */
#endif