Ocean
Loading...
Searching...
No Matches
Engine.h
Go to the documentation of this file.
1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 *
4 * This source code is licensed under the MIT license found in the
5 * LICENSE file in the root directory of this source tree.
6 */
7
8#ifndef META_OCEAN_RENDERING_ENGINE_H
9#define META_OCEAN_RENDERING_ENGINE_H
10
14
16
17namespace Ocean
18{
19
20namespace Rendering
21{
22
23// Forward declaration
24class Engine;
25
26/**
27 * Definition of an engine reference object.
28 * @ingroup rendering
29 */
31
32/**
33 * This class is the base class for all rendering engines like.<br>
34 * The main task of this class is to provide a framebuffer and a factory to create and render geometry nodes.<br>
35 * The factory is able to create all supported rendering nodes and objects.<br>
36 * The framebuffer holds the scene, the view and the resulting frame.<br>
37 * Beware: Do not use the derivated instances of this object.<br>
38 *
39 * The manager holds and manages all engine instances for the registered rendering plugins like e.g. Nvidia SceniX or the GLESceneGraph.<br>
40 * Therefore, receive an engine instance for a specific render engine from the manager only.<br>
41 * Afterwards, the engine must be initialized before usage.<br>
42 * @see Factory, Framebuffer, Manager
43 * @ingroup rendering
44 */
45class OCEAN_RENDERING_EXPORT Engine
46{
47 friend class DynamicObject;
48 friend class Manager;
49 friend class Ocean::ObjectRef<Engine>;
50
51 public:
52
53 /**
54 * Definition of different graphic APIs.
55 */
56 enum GraphicAPI : uint32_t
57 {
58 /// Invalid graphic api id.
59 API_DEFAULT = 0u,
60 /// OpenGL graphic api id.
61 API_OPENGL = 1u,
62 /// OpenGL ES graphic api id.
63 API_OPENGLES = 2u,
64 /// DirectX graphic api id.
65 API_DIRECTX = 4u,
66 /// Raytracer graphic api id.
67 API_RAYTRACER = 8u
68 };
69
70 /**
71 * Definition of a callback function used to create a registered engine.
72 */
74
75 /**
76 * Definition of a vector holding framebuffer references.
77 */
78 typedef std::vector<FramebufferRef> Framebuffers;
79
80 protected:
81
82 /**
83 * Definition of a vector holding framebuffer ids.
84 */
85 typedef std::vector<ObjectId> ObjectIds;
86
87 public:
88
89 /**
90 * Returns the factory of this render engine.
91 * @return Factory of render engine
92 */
93 virtual const Factory& factory() const = 0;
94
95 /**
96 * Returns all created and valid framebuffer.
97 * @return Framebuffer references
98 */
100
101 /**
102 * Returns a new framebuffer of this render engine.
103 * This function return the framebuffer created by the internal create framebuffer function.
104 * @param type Type of the framebuffer to be created
105 * @param config The configuration of the framebuffer to create
106 * @see Framebuffer, internalCreateFramebuffer().
107 * @return New framebuffer of this render engine
108 */
109 FramebufferRef createFramebuffer(const Framebuffer::FramebufferType type = Framebuffer::FRAMEBUFFER_WINDOW, const Framebuffer::FramebufferConfig& config = {});
110
111 /**
112 * Returns the name of this engine.
113 * @return Engine name
114 */
115 virtual const std::string& engineName() const = 0;
116
117 /**
118 * Returns the selected graphic API.
119 * @return Graphic API
120 */
121 inline GraphicAPI graphicAPI() const;
122
123 /**
124 * Returns the graphic APIs supported by this engine.
125 * @return Supported graphic APIs.
126 */
127 inline GraphicAPI supportedAPIs() const;
128
129 /**
130 * Updates dynamic objects in the engine.
131 * @param timestamp The current timestamp to be used to update the dynamic objects, e.g., to control animations or video textures, must be valid
132 */
133 virtual void update(const Timestamp timestamp);
134
135 /**
136 * Returns an object by a given object id belonging to this engine.
137 * If the object does not exist an empty reference is returned.
138 * @param objectId Id of the object to return
139 * @return Object reference of the requested object
140 * @see ObjectRefManager::object().
141 */
142 ObjectRef object(const ObjectId objectId) const;
143
144 /**
145 * Returns the first object having a specified name and belonging to this engine.
146 * If the object does not exist an empty reference is returned.
147 * @param name The name of the object to return
148 * @return Object reference of the requested object
149 * @see ObjectRefManager::object().
150 */
151 ObjectRef object(const std::string& name) const;
152
153 /**
154 * Returns all objects having a specified name and belonging to this engine.
155 * @param name The name of the objects to return
156 * @return Specified objects
157 * @see ObjectRefManager::objects().
158 */
159 ObjectRefs objects(const std::string& name) const;
160
161 /**
162 * Returns the extensions supported by the first created framebuffer.
163 * @return Supported extensions separated by a blank
164 */
165 virtual std::string extensions() const;
166
167 /**
168 * Returns whether the first framebuffer created by this engine supports a specific extension.
169 * @param extension Extension to check
170 * @return True, if the extension is supported
171 */
172 virtual bool hasExtension(const std::string& extension) const;
173
174 /**
175 * Returns the recent timestamp of the engine.
176 * The engine's timestamp controls e.g., animations or video textures.
177 * @return The engine's recent timestamp
178 */
179 inline Timestamp timestamp() const;
180
181 /**
182 * Retruns the lock object of this engine.
183 * Beware: Use this lock with caution.
184 * @return Engine lock object
185 */
186 inline Lock& lock() const;
187
188 /**
189 * Returns the render lock of this engine.
190 * The lock should be locked whenever a frame rendering is invoked related to this engine.
191 * @return Rendering lock object
192 */
193 inline Lock& renderLock();
194
195 protected:
196
197 /**
198 * Disabled copy constructor.
199 * @param engine Object which would be copied
200 */
201 Engine(const Engine& engine) = delete;
202
203 /**
204 * Creates a new render engine.
205 * @param graphicAPI Supported graphic APIs
206 */
207 Engine(const GraphicAPI graphicAPI);
208
209 /**
210 * Destructs a render engine.
211 */
212 virtual ~Engine();
213
214 /**
215 * Registers a new dynamic object.
216 * @param object Dynamic object to register
217 */
219
220 /**
221 * Unregisters a dynamic object.
222 * @param object Dynamic object to unregister
223 */
225
226 /**
227 * Returns a framebuffer reference of a just created framebuffer object.
228 * @param type Type of the framebuffer to be created
229 * @param config The configuration of the framebuffer to create
230 * @return New framebuffer to create a reference from
231 */
233
234 /**
235 * Disabled copy operator.
236 * @param engine Object which would be copied
237 * @return Reference to this object
238 */
239 Engine& operator=(const Engine& engine) = delete;
240
241 /**
242 * Registers an engine at the manager.
243 * @param engineName Name of the engine to register
244 * @param callback Engine create callback to create an engine object on demand
245 * @param graphicAPI Graphic API supported by the given engine
246 * @param priority Priority of this engine, if a default engine is requested the engine with higher priority will be retuned
247 */
248 static void registerEngine(const std::string& engineName, const CreateCallback& callback, const GraphicAPI graphicAPI, const unsigned int priority);
249
250 /**
251 * Unregisters an engine at the manager.
252 * @param engine Name of the engine to unregister
253 * @return True, if succeeded
254 */
255 static bool unregisterEngine(const std::string& engine);
256
257 protected:
258
259 /// Selected graphic API.
261
262 /// Supported graphic API.
264
265 /// Vector holding ids of all registered dynamic objects for this engine.
267
268 /// The recent timestamp of the engine, to control e.g., animations or video textures
270
271 /// Vector holding all ids of created framebuffers.
273
274 /// Engine lock.
275 mutable Lock lock_;
276
277 /// Render lock.
279
280 /// Dynamic object lock.
282};
283
285{
286 return graphicAPI_;
287}
288
293
295{
296 const ScopedLock scopedLock(lock_);
297
298 return timestamp_;
299}
300
301inline Lock& Engine::lock() const
302{
303 return lock_;
304}
305
307{
308 return renderLock_;
309}
310
311}
312
313}
314
315#endif // META_OCEAN_RENDERING_ENGINE_H
This class implements a container for callback functions.
Definition Callback.h:3456
This class implements a recursive lock object.
Definition Lock.h:31
This template class implements a object reference with an internal reference counter.
Definition base/ObjectRef.h:58
This class is the base class for all dynamic scene graph objects.
Definition DynamicObject.h:40
This class is the base class for all rendering engines like.
Definition Engine.h:46
GraphicAPI graphicAPI() const
Returns the selected graphic API.
Definition Engine.h:284
GraphicAPI supportedAPIs() const
Returns the graphic APIs supported by this engine.
Definition Engine.h:289
GraphicAPI graphicAPI_
Selected graphic API.
Definition Engine.h:260
Lock renderLock_
Render lock.
Definition Engine.h:278
ObjectRef object(const ObjectId objectId) const
Returns an object by a given object id belonging to this engine.
Engine(const Engine &engine)=delete
Disabled copy constructor.
std::vector< ObjectId > ObjectIds
Definition of a vector holding framebuffer ids.
Definition Engine.h:85
Engine(const GraphicAPI graphicAPI)
Creates a new render engine.
Lock & renderLock()
Returns the render lock of this engine.
Definition Engine.h:306
static bool unregisterEngine(const std::string &engine)
Unregisters an engine at the manager.
ObjectIds framebufferIds_
Vector holding all ids of created framebuffers.
Definition Engine.h:272
virtual std::string extensions() const
Returns the extensions supported by the first created framebuffer.
static void registerEngine(const std::string &engineName, const CreateCallback &callback, const GraphicAPI graphicAPI, const unsigned int priority)
Registers an engine at the manager.
ObjectRefs objects(const std::string &name) const
Returns all objects having a specified name and belonging to this engine.
virtual Framebuffer * internalCreateFramebuffer(const Framebuffer::FramebufferType type, const Framebuffer::FramebufferConfig &config)=0
Returns a framebuffer reference of a just created framebuffer object.
void unregisterDynamicObject(DynamicObject *object)
Unregisters a dynamic object.
Lock objectLock_
Dynamic object lock.
Definition Engine.h:281
FramebufferRef createFramebuffer(const Framebuffer::FramebufferType type=Framebuffer::FRAMEBUFFER_WINDOW, const Framebuffer::FramebufferConfig &config={})
Returns a new framebuffer of this render engine.
virtual bool hasExtension(const std::string &extension) const
Returns whether the first framebuffer created by this engine supports a specific extension.
virtual ~Engine()
Destructs a render engine.
virtual const Factory & factory() const =0
Returns the factory of this render engine.
Callback< Engine *, const GraphicAPI > CreateCallback
Definition of a callback function used to create a registered engine.
Definition Engine.h:73
ObjectIds dynamicObjects_
Vector holding ids of all registered dynamic objects for this engine.
Definition Engine.h:266
Lock lock_
Engine lock.
Definition Engine.h:275
const GraphicAPI supportedGraphicAPIs_
Supported graphic API.
Definition Engine.h:263
Engine & operator=(const Engine &engine)=delete
Disabled copy operator.
virtual void update(const Timestamp timestamp)
Updates dynamic objects in the engine.
virtual const std::string & engineName() const =0
Returns the name of this engine.
Timestamp timestamp() const
Returns the recent timestamp of the engine.
Definition Engine.h:294
Framebuffers framebuffers() const
Returns all created and valid framebuffer.
Lock & lock() const
Retruns the lock object of this engine.
Definition Engine.h:301
ObjectRef object(const std::string &name) const
Returns the first object having a specified name and belonging to this engine.
std::vector< FramebufferRef > Framebuffers
Definition of a vector holding framebuffer references.
Definition Engine.h:78
void registerDynamicObject(DynamicObject *object)
Registers a new dynamic object.
Timestamp timestamp_
The recent timestamp of the engine, to control e.g., animations or video textures.
Definition Engine.h:269
GraphicAPI
Definition of different graphic APIs.
Definition Engine.h:57
This class implements a node and object factory.
Definition rendering/Factory.h:30
This class holds framebuffer configurations.
Definition rendering/Framebuffer.h:94
This class is the base class for all rendering framebuffers.
Definition rendering/Framebuffer.h:48
FramebufferType
Definition of different framebuffer types.
Definition rendering/Framebuffer.h:55
This class manages all scene graphs.
Definition rendering/Manager.h:31
This class implements a scoped lock object for recursive lock objects.
Definition Lock.h:135
This class implements a timestamp.
Definition Timestamp.h:36
Ocean::ObjectRef< Engine > EngineRef
Definition of an engine reference object.
Definition Engine.h:30
std::vector< ObjectRef > ObjectRefs
Definition of a vector holding rendering object references.
Definition Object.h:41
The namespace covering the entire Ocean framework.
Definition Accessor.h:15