1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
/*! \page pageextserialization Serialization (NvBlastExtSerialization)
\section serialization_intro Introduction
This extension defines the Nv::Blast::ExtSerialization class, a modular serialization manager which can be extended to handle data types from different Blast&tm; modules
(such as low-level, Tk, and ExtPhysX).
An ExtSerialization manager is created using the global function NvBlastExtSerializationCreate:
(From now on we'll assume we are using the Nv::Blast namespace.)
\code
ExtSerialization* ser = NvBlastExtSerializationCreate();
\endcode
ExtSerialization is capable of loading sets of serializers for different data types and encodings. The NvBlastExtSerialization extension comes with a set of low-level data serializers,
with types enumerated in the header <b>NvBlastExtLlSerialization.h</b>.
<b>The low-level serializers are automatically loaded into an ExtSerialization when it is created.</b>
To load serializers for Tk and ExtPhysX assets, you must also load the extensions \ref pageexttkserialization and \ref pageextpxserialization, respectively. See the documentation for
those modules.
Each serializer is capable of reading (and writing, if it is not read-only) a single data type in a single encoding (format). Some serializers are read-only, in order to read legacy
formats.
The encodings available are enumerated in ExtSerialization::EncodingID. They are currently:
- CapnProtoBinary - Uses Cap'n Proto's binary serialization format
- Raw - For low-level NvBlastAsset and NvBlastFamily types, this is simply a memory copy. For Tk and ExtPx assets, this is the deprecated serialization format from Blast&tm; 1.0.
<br>
\section serialization_ser Serialization (writing)
To serialize an object, the serialization manager's write encoding ID must be set to the desired value. By default it is set to EncodingID::CapnProtoBinary, as this is the only
encoding which supports writing for all object types (at the present time). When other encodings become available, use ExtSerialization::setSerializationEncoding to set the write
encoding to the desired type.
Each serialization module defines the object types it can serialize. ExtSerialization defines the low-level types in <b>NvBlastExtLlSerialization.h</b>:
- LlObjectTypeID::Asset - An NvBlastAsset
- LlObjectTypeID::Family - An NvBlastFamily
To serialize an object, for example an NvBlastAsset, use ExtSerialization::serializeIntoBuffer as follows:
\code
const NvBlastAsset* asset = ... // Given pointer to an NvBlastAsset
void* buffer;
uint64_t size = ser->serializeIntoBuffer(buffer, asset, LlObjectTypeID::Asset);
\endcode
If successful, the data is written into a buffer allocated using the NvBlastGlobals allocator, written to the "buffer" parameter, and the size of the buffer
written is the return value of the function. If the function returns 0, then serialization was unsuccessful. Notice that the second function parameter is actually a void*,
so it requires the last parameter to tell it what object it is serializing. A utility wrapper function is given in <b>NvBlastExtLlSerialization.h</b> which performs the
same operation with an NvBlastAsset, so one could equivalently use
\code
void* buffer;
uint64_t size = NvBlastExtSerializationSerializeAssetIntoBuffer(buffer, *ser, asset);
\endcode
A corresponding function also exists for NvBlastFamily, as well as other data types supported by other serialization extensions.
This buffer may be written to disk, memory, networked, etc. Since the memory for the buffer is allocated using the allocator
in NvBlastGlobals, it may be freed using the same allocator:
\code
NVBLAST_FREE(buffer)
\endcode
<br>
\subsection bufferproviders Using a Buffer Provider
If you wish to provide the serialization buffer by some means other than the NvBlastGlobals allocator, you may set a "buffer provider"
in the serialization manager. A buffer provider is simply a callback that requests a buffer from the user of the necessary size.
The user implements the interface ExtSerialization::BufferProvider, and passes a pointer to an instance of one to the serialization
manager using ExtSerialization::setBufferProvider.
For example:
\code
std::vector<char> growableBuffer;
class MyBufferProvider : public Nv::Blast::ExtSerialization::BufferProvider
{
public:
MyBufferProvider(std::vector<char>& growableBuffer) : m_growableBuffer(growableBuffer) {}
virtual void* requestBuffer(size_t size) override
{
if (m_growableBuffer.size() < size)
{
m_growableBuffer.resize(size);
}
return m_growableBuffer.data();
}
private:
std::vector<char>& m_growableBuffer;
} myBufferProvider(growableBuffer);
ser->setBufferProvider(&myBufferProvider);
\endcode
Passing NULL to setBufferProvider returns the serialization to its default behavior of using the NvBlastGlobals allocator.
<br>
\section serialization_deser Deserialization (reading)
To deserialize an object, use the ExtSerialization::deserializeFromBuffer method. If you know the type of object in the buffer,
you may directly cast the returned pointer to one of that type. For example, if the buffer contains an NvBlastAsset, use:
\code
const void* buffer = ... // A given buffer, may be read from disk, memory, etc.
const uint64_t size = ... // The buffer's size in bytes
NvBlastAsset* asset = static_cast<NvBlastAsset*>(ser->deserializeFromBuffer(buffer, size));
\endcode
This returns a valid pointer if deserialization was successful, or NULL otherwise. If no serializer is loaded which can handle
the object type in the stream in its given encoding, it will fail and return NULL.
Again, the memory for the asset is allocated using NvBlastGlobals, so that the asset may be released using
\code
NVBLAST_FREE(asset);
\endcode
<br>
\section detecting_object_type Detecting the Object Type in a Buffer
If you don't know the object type in the buffer, you may use the last (optional) argument in deserializeFromBuffer to return the type:
\code
uint32_t objTypeID;
void* obj = ser->deserializeFromBuffer(buffer, size, &objTypeID);
NVBLAST_CHECK_ERROR(obj != nullptr, "Object could not be read from buffer.", return);
switch (objTypeID)
{
case LlObjectTypeID::Asset:
handleAssetLoad(static_cast<NvBlastAsset*>(obj));
break;
case LlObjectTypeID::Family:
handleFamilyLoad(static_cast<NvBlastFamily*>(obj));
break;
default:
NVBLAST_LOG_ERROR("Unknown object type ");
}
\endcode
<br>
\subsection peeking_and_skipping Peeking at and Skipping Buffer Data
If a buffer contains multiple objects, you may peek at the buffer to get object information including object type, encoding, and data size, and skip to
the next object in the buffer (whether or not you have chosen to read the current object). For example:
\code
const void* buffer = ... // The input buffer
uint64_t size = ... // The input buffer size
while (size)
{
uint64_t objTypeID;
if (!ser->peekHeader(&objTypeID, NULL, NULL, buffer, size)) // Only reading the object type ID; may pass in NULL for the other header value pointers
{
break; // Read error, stop
}
if (objectShouldBeLoaded(objTypeID)) // Some function to determine whether or not we want this object
{
void* obj = ser->deserializeFromBuffer(buffer, size);
// Handle loaded object ...
}
// Jump to next object:
buffer = ser->skipObject(size, buffer); // Updates size as well
}
\endcode
<br>
\section serialization_term Cleaning Up
When finished with the serialization manager, it may be released using its release() method:
\code
ser->release();
\endcode
<br>
*/
|