1//************************************ bs::framework - Copyright 2018 Marko Pintera **************************************//
2//*********** Licensed under the MIT license. See LICENSE.md for full terms. This notice is not to be removed. ***********//
3#pragma once
4
5#include "Prerequisites/BsPrerequisitesUtil.h"
6#include "Utility/BsAny.h"
7
8namespace bs
9{
10 class RTTITypeBase;
11
12 /** @addtogroup Internal-Utility
13 * @{
14 */
15
16 /** @addtogroup RTTI-Internal
17 * @{
18 */
19
20 /**
21 * Types of fields we can serialize:
22 *
23 * - Plain - Native data types, POD (Plain old data) structures, or in general types we don't want to (or can't) inherit from IReflectable.
24 * Type must be copyable by memcpy.
25 *
26 * - DataBlock - Array of bytes of a certain size. When returning a data block you may specify if its managed or unmanaged.
27 * Managed data blocks have their buffers deleted after they go out of scope. This is useful if you need to return some
28 * temporary data. On the other hand if the data in the block belongs to your class, and isn't temporary, keep the data unmanaged.
29 *
30 * - Reflectable - Field that is of IReflectable type. Cannot be a pointer to IReflectable and must be actual value type.
31 * Type and its fields are serialized recursively. Supports versioning so you may add/remove fields from the type
32 * without breaking previously serialized data.
33 *
34 * - ReflectablePtr - A pointer to IReflectable. Same as "Reflectable" except that data isn't serialized as a value type,
35 * but as a pointer, which may be referenced by multiple other instances. All references are saved upon
36 * serialization and restored upon deserialization.
37 */
38 enum SerializableFieldType
39 {
40 SerializableFT_Plain,
41 SerializableFT_DataBlock,
42 SerializableFT_Reflectable,
43 SerializableFT_ReflectablePtr
44 };
45
46 /** Various flags you can assign to RTTI fields. */
47 enum class RTTIFieldFlag
48 {
49 /**
50 * This flag is only used on field types of ReflectablePtr type, and it is used
51 * to solve circular references. Circular references cause an issue when deserializing,
52 * as the algorithm doesn't know which object to deserialize first. By making one of
53 * the references weak, you tell the algorithm that it doesn't have to guarantee
54 * the object will be fully deserialized before being assigned to the field.
55 *
56 * In short: If you make a reference weak, when "set" method of that field is called,
57 * it is not guaranteed the value provided is fully initialized, so you should not access any of its
58 * data until deserialization is fully complete. You only need to use this flag if the RTTI system
59 * complains that is has found a circular reference.
60 */
61 WeakRef = 1 << 0,
62 /**
63 * This flags signals various systems that the flagged field should not be searched when looking for
64 * object references. This normally means the value of this field will no be retrieved during reference
65 * searches but it will likely still be retrieved during other operations (for example serialization).
66 * This is used as an optimization to avoid retrieving values of potentially very expensive fields that
67 * would not contribute to the reference search anyway. Whether or not a field contributes to the reference
68 * search depends on the search and should be handled on a case by case basis.
69 */
70 SkipInReferenceSearch = 1 << 1,
71 /**
72 * Lets the replication system know that this field should be monitored for changes and replicated across the
73 * network when changes are detected.
74 */
75 Replicate = 1 << 2
76 };
77
78 typedef Flags<RTTIFieldFlag> RTTIFieldFlags;
79 BS_FLAGS_OPERATORS(RTTIFieldFlag)
80
81 /** Provides various optional information regarding a RTTI field. */
82 struct BS_UTILITY_EXPORT RTTIFieldInfo
83 {
84 RTTIFieldFlags flags;
85
86 RTTIFieldInfo() = default;
87
88 RTTIFieldInfo(RTTIFieldFlags flags)
89 :flags(flags)
90 { }
91
92 static RTTIFieldInfo DEFAULT;
93 };
94
95 /**
96 * Structure that keeps meta-data concerning a single class field. You can use this data for setting and getting values
97 * for that field on a specific class instance.
98 *
99 * Class also contains an unique field name, and an unique field ID. Fields may contain single types or an array of types.
100 * See SerializableFieldType for information about specific field types.
101 *
102 * @note
103 * Most of the methods for retrieving and setting data accept "void *" for both the data and the owning class instance.
104 * It is up to the caller to ensure that pointer is of proper type.
105 */
106 struct BS_UTILITY_EXPORT RTTIField
107 {
108 String mName;
109 UINT16 mUniqueId;
110 bool mIsVectorType;
111 SerializableFieldType mType;
112 RTTIFieldInfo mInfo;
113
114 virtual ~RTTIField() = default;
115
116 /** Checks is the field plain type and castable to RTTIPlainFieldBase. */
117 bool isPlainType() const { return mType == SerializableFT_Plain; }
118
119 /** Checks is the field a data block type and castable to RTTIManagedDataBlockFieldBase. */
120 bool isDataBlockType() const { return mType == SerializableFT_DataBlock; }
121
122 /** Checks is the field a reflectable type and castable to RTTIReflectableFieldBase. */
123 bool isReflectableType() const { return mType == SerializableFT_Reflectable; }
124
125 /** Checks is the field a reflectable pointer type and castable to RTTIReflectablePtrFieldBase. */
126 bool isReflectablePtrType() const { return mType == SerializableFT_ReflectablePtr; }
127
128 /** Checks is the field contains an array or a single entry. */
129 bool isArray() const { return mIsVectorType; }
130
131 /** Returns additional information about the field. */
132 const RTTIFieldInfo& getInfo() const { return mInfo; }
133
134 /**
135 * Gets the size of an array contained by the field, if the field represents an array. Throws exception if field
136 * is not an array.
137 */
138 virtual UINT32 getArraySize(RTTITypeBase* rtti, void* object) = 0;
139
140 /**
141 * Changes the size of an array contained by the field, if the field represents an array. Throws exception if field
142 * is not an array.
143 */
144 virtual void setArraySize(RTTITypeBase* rtti, void* object, UINT32 size) = 0;
145
146 /** Returns the type id for the type used in this field. */
147 virtual UINT32 getTypeSize() = 0;
148
149 /**
150 * Query if the field has dynamic size.
151 *
152 * @note
153 * Field should have dynamic size if:
154 * - The field can have varying size
155 * - The field size is over 255
156 * @note
157 * Types like integers, floats, bools, POD structs dont have dynamic size.
158 * Types like strings, vectors, maps do.
159 * @note
160 * If your type has a static size but that size exceeds 255 bytes you also need to
161 * use dynamic field size. (You will be warned during compilation if you don't follow this rule)
162 */
163 virtual bool hasDynamicSize() = 0;
164
165 /**
166 * Throws an exception if this field doesn't contain a plain value.
167 *
168 * @param[in] array If true then the field must support plain array type.
169 */
170 void checkIsPlain(bool array);
171
172 /**
173 * Throws an exception if this field doesn't contain a complex value.
174 *
175 * @param[in] array If true then the field must support complex array type.
176 */
177 void checkIsComplex(bool array);
178
179 /**
180 * Throws an exception if this field doesn't contain a complex pointer value.
181 *
182 * @param[in] array If true then the field must support complex pointer array type.
183 */
184 void checkIsComplexPtr(bool array);
185
186 /**
187 * Throws an exception depending if the field is or isn't an array.
188 *
189 * @param[in] array If true, then exception will be thrown if field is not an array.
190 * If false, then it will be thrown if field is an array.
191 */
192 void checkIsArray(bool array);
193
194 /** Throws an exception if this field doesn't contain a data block value. */
195 void checkIsDataBlock();
196
197 protected:
198 void init(String name, UINT16 uniqueId, bool isVectorType, SerializableFieldType type, const RTTIFieldInfo& info)
199 {
200 this->mName = std::move(name);
201 this->mUniqueId = uniqueId;
202 this->mIsVectorType = isVectorType;
203 this->mType = type;
204 this->mInfo = info;
205 }
206 };
207
208 /** @} */
209 /** @} */
210}
211