This class is the main interface to controlling the render process. More...
#include "graphicsEngine.h"
Public Types | |
| enum | ThreadState { TS_wait, TS_do_frame, TS_do_flip, TS_do_release, TS_do_windows, TS_do_compute, TS_do_extract, TS_do_screenshot, TS_terminate, TS_done } |
Public Member Functions | |
| GraphicsEngine (Pipeline *pipeline=nullptr) | |
| Creates a new GraphicsEngine object. More... | |
| ~GraphicsEngine () | |
| Gracefully cleans up the graphics engine and its related threads and windows. More... | |
| bool | add_window (GraphicsOutput *window, int sort) |
| This can be used to add a newly-created GraphicsOutput object (and its GSG) to the engine's list of windows, and requests that it be opened. More... | |
| void | dispatch_compute (const LVecBase3i &work_groups, const ShaderAttrib *sattr, GraphicsStateGuardian *gsg) |
| Asks the indicated GraphicsStateGuardian to dispatch the compute shader in the given ShaderAttrib using the given work group counts. More... | |
| bool | extract_texture_data (Texture *tex, GraphicsStateGuardian *gsg) |
| Asks the indicated GraphicsStateGuardian to retrieve the texture memory image of the indicated texture and store it in the texture's ram_image field. More... | |
| void | flip_frame () |
| Waits for all the threads that started drawing their last frame to finish drawing, and then flips all the windows. More... | |
| bool | get_auto_flip () const |
| Loader * | get_default_loader () const |
| int | get_num_windows () const |
| bool | get_portal_cull () const |
| const ReMutex & | get_render_lock () const |
| GraphicsThreadingModel | get_threading_model () const |
| GraphicsOutput * | get_window (int n) const |
| bool | is_empty () const |
| Returns true if there are no windows or buffers managed by the engine, false if there is at least one. More... | |
| GraphicsOutput * | make_buffer (GraphicsOutput *host, const std::string &name, int sort, int x_size, int y_size) |
| Syntactic shorthand for make_output. More... | |
| GraphicsOutput * | make_buffer (GraphicsStateGuardian *gsg, const std::string &name, int sort, int x_size, int y_size) |
| Syntactic shorthand for make_output. More... | |
| GraphicsOutput * | make_output (GraphicsPipe *pipe, const std::string &name, int sort, const FrameBufferProperties &fb_prop, const WindowProperties &win_prop, int flags, GraphicsStateGuardian *gsg=nullptr, GraphicsOutput *host=nullptr) |
| Creates a new window (or buffer) and returns it. More... | |
| GraphicsOutput * | make_parasite (GraphicsOutput *host, const std::string &name, int sort, int x_size, int y_size) |
| Syntactic shorthand for make_buffer. More... | |
| void | open_windows () |
| Fully opens (or closes) any windows that have recently been requested open or closed, without rendering any frames. More... | |
| PT (Texture) do_get_screenshot(DisplayRegion *region | |
| void | ready_flip () |
| Waits for all the threads that started drawing their last frame to finish drawing. More... | |
| void | remove_all_windows () |
| Removes and closes all windows from the engine. More... | |
| bool | remove_window (GraphicsOutput *window) |
| Removes the indicated window or offscreen buffer from the set of windows that will be processed when render_frame() is called. More... | |
| void | render_frame () |
| Renders the next frame in all the registered windows, and flips all of the frame buffers. More... | |
| void | reset_all_windows (bool swapchain) |
| Resets the framebuffer of the current window. More... | |
| void | set_auto_flip (bool auto_flip) |
| void | set_default_loader (Loader *loader) |
| void | set_portal_cull (bool value) |
| void | set_threading_model (const GraphicsThreadingModel &threading_model) |
| void | sync_frame () |
| Waits for all the threads that started drawing their last frame to finish drawing. More... | |
| void | texture_uploaded (Texture *tex) |
| This method is called by the GraphicsStateGuardian after a texture has been successfully uploaded to graphics memory. More... | |
 Public Member Functions inherited from ReferenceCount | |
| int | get_ref_count () const |
| WeakReferenceList * | get_weak_list () const |
| Returns the WeakReferenceList associated with this ReferenceCount object. More... | |
| bool | has_weak_list () const |
| Returns true if this particular ReferenceCount object has a WeakReferenceList created, false otherwise. More... | |
| void | local_object () |
| This function should be called, once, immediately after creating a new instance of some ReferenceCount-derived object on the stack. More... | |
| void | ref () const |
| Explicitly increments the reference count. More... | |
| bool | ref_if_nonzero () const |
| Atomically increases the reference count of this object if it is not zero. More... | |
| bool | test_ref_count_integrity () const |
| Does some easy checks to make sure that the reference count isn't completely bogus. More... | |
| bool | test_ref_count_nonzero () const |
| Does some easy checks to make sure that the reference count isn't zero, or completely bogus. More... | |
| virtual bool | unref () const |
| Explicitly decrements the reference count. More... | |
| WeakReferenceList * | weak_ref () |
| Adds the indicated PointerToVoid as a weak reference to this object. More... | |
| void | weak_unref () |
| Removes the indicated PointerToVoid as a weak reference to this object. More... | |
Static Public Member Functions | |
| static void | do_cull (CullHandler *cull_handler, SceneSetup *scene_setup, GraphicsStateGuardian *gsg, Thread *current_thread) |
| Fires off a cull traversal using the indicated camera. More... | |
| static GraphicsEngine * | get_global_ptr () |
| Static Public Member Functions inherited from ReferenceCount | |
| static TypeHandle | get_class_type () |
| static void | init_type () |
Public Attributes | |
| get_auto_flip | |
| Returns the current setting for the auto-flip flag. More... | |
| get_default_loader | |
| Returns the Loader object that will be assigned to every GSG created with this GraphicsEngine. More... | |
| get_num_windows | |
| Returns the number of windows (or buffers) managed by the engine. More... | |
| get_portal_cull | |
| Returns the current setting for the portal culling flag. More... | |
| get_render_lock | |
| Returns a ReMutex object that is held by the GraphicsEngine during the entire call to render_frame(). More... | |
| get_threading_model | |
| Returns the threading model that will be applied to future objects. More... | |
| get_window | |
| Returns the nth window or buffers managed by the engine, in sorted order. More... | |
| GraphicsStateGuardian * | gsg |
| set_auto_flip | |
| Set this flag true to indicate the GraphicsEngine should automatically cause windows to sync and flip as soon as they have finished drawing, rather than waiting for all of the windows to finish drawing first so they can flip together. More... | |
| set_default_loader | |
| Sets the Loader object that will be assigned to every GSG created with this GraphicsEngine. More... | |
| set_portal_cull | |
| Set this flag true to indicate the GraphicsEngine should start portal culling. More... | |
| set_threading_model | |
| Specifies how future objects created via make_gsg(), make_buffer(), and make_window() will be threaded. More... | |
| Public Attributes inherited from ReferenceCount | |
| get_ref_count | |
| Returns the current reference count. More... | |
Friends | |
| class | GraphicsOutput |
| class | WindowRenderer |
Detailed Description
This class is the main interface to controlling the render process.
There is typically only one GraphicsEngine in an application, and it synchronizes rendering to all all of the active windows; although it is possible to have multiple GraphicsEngine objects if multiple synchronicity groups are required.
The GraphicsEngine is responsible for managing the various cull and draw threads. The application simply calls engine->render_frame() and considers it done.
Definition at line 53 of file graphicsEngine.h.
Constructor & Destructor Documentation
◆ GraphicsEngine()
|
explicit |
Creates a new GraphicsEngine object.
The Pipeline is normally left to default to NULL, which indicates the global render pipeline, but it may be any Pipeline you choose.
Definition at line 147 of file graphicsEngine.cxx.
References Pipeline::get_render_pipeline(), and set_threading_model.
◆ ~GraphicsEngine()
| GraphicsEngine::~GraphicsEngine | ( | ) |
Gracefully cleans up the graphics engine and its related threads and windows.
Definition at line 178 of file graphicsEngine.cxx.
References remove_all_windows().
Member Function Documentation
◆ add_window()
| bool GraphicsEngine::add_window | ( | GraphicsOutput * | window, |
| int | sort | ||
| ) |
This can be used to add a newly-created GraphicsOutput object (and its GSG) to the engine's list of windows, and requests that it be opened.
This shouldn't be called by user code as make_output normally does this under the hood; it may be useful in esoteric cases in which a custom window object is used.
This can be called during the rendering loop, unlike make_output(); the window will be opened before the next frame begins rendering. Because it doesn't call open_windows(), however, it's not guaranteed that the window will succeed opening even if it returns true.
Definition at line 485 of file graphicsEngine.cxx.
◆ dispatch_compute()
| void GraphicsEngine::dispatch_compute | ( | const LVecBase3i & | work_groups, |
| const ShaderAttrib * | sattr, | ||
| GraphicsStateGuardian * | gsg | ||
| ) |
Asks the indicated GraphicsStateGuardian to dispatch the compute shader in the given ShaderAttrib using the given work group counts.
This can act as an interface for running a one-off compute shader, without having to store it in the scene graph using a ComputeNode.
Since this requires a round-trip to the draw thread, it may require waiting for the current thread to finish rendering if it is called in a multithreaded environment. However, you can call this several consecutive times on different textures for little additional cost.
The return value is true if the operation is successful, false otherwise.
Definition at line 1176 of file graphicsEngine.cxx.
◆ do_cull()
|
static |
Fires off a cull traversal using the indicated camera.
Definition at line 1303 of file graphicsEngine.cxx.
References DisplayRegion::get_cull_region_pcollector(), DisplayRegion::get_cull_traverser, SceneSetup::get_display_region(), and DisplayRegion::get_incomplete_render.
◆ extract_texture_data()
| bool GraphicsEngine::extract_texture_data | ( | Texture * | tex, |
| GraphicsStateGuardian * | gsg | ||
| ) |
Asks the indicated GraphicsStateGuardian to retrieve the texture memory image of the indicated texture and store it in the texture's ram_image field.
The image can then be written to disk via Texture::write(), or otherwise manipulated on the CPU.
This is useful for retrieving the contents of a texture that has been somehow generated on the graphics card, instead of having been loaded the normal way via Texture::read() or Texture::load(). It is particularly useful for getting the data associated with a compressed texture image.
Since this requires a round-trip to the draw thread, it may require waiting for the current thread to finish rendering if it is called in a multithreaded environment. However, you can call this several consecutive times on different textures for little additional cost.
If the texture has not yet been loaded to the GSG in question, it will be loaded immediately.
The return value is true if the operation is successful, false otherwise.
Definition at line 1118 of file graphicsEngine.cxx.
References GraphicsStateGuardian::extract_texture_data(), GraphicsThreadingModel::get_draw_name(), and GraphicsStateGuardian::get_threading_model().
◆ flip_frame()
| void GraphicsEngine::flip_frame | ( | ) |
Waits for all the threads that started drawing their last frame to finish drawing, and then flips all the windows.
It is not usually necessary to call this explicitly, unless you need to see the previous frame right away.
Definition at line 1087 of file graphicsEngine.cxx.
◆ is_empty()
| bool GraphicsEngine::is_empty | ( | ) | const |
Returns true if there are no windows or buffers managed by the engine, false if there is at least one.
Definition at line 664 of file graphicsEngine.cxx.
References ordered_vector< Key, Compare, Vector >::empty().
◆ make_buffer() [1/2]
|
inline |
Syntactic shorthand for make_output.
This is the preferred way to create an offscreen buffer, when you already have an onscreen window or another buffer to start with. For the first parameter, pass an existing GraphicsOutput object, e.g. the main window; this allows the buffer to adapt itself to that window's framebuffer properties, and allows maximum sharing of resources.
Definition at line 107 of file graphicsEngine.I.
References GraphicsOutput::get_gsg, GraphicsOutput::get_pipe, make_output(), and WindowProperties::size().
◆ make_buffer() [2/2]
|
inline |
Syntactic shorthand for make_output.
This flavor accepts a GSG rather than a GraphicsOutput as the first parameter, which is too limiting and disallows the possibility of creating a ParasiteBuffer if the user's graphics hardware prefers that. It also attempts to request specific framebuffer properties and may therefore do a poorer job of sharing the GSG between the old buffer and the new.
For these reasons, this variant is a poor choice unless you are creating an offscreen buffer for the first time, without an onscreen window already in existence. If you already have an onscreen window, you should use the other flavor of make_buffer() instead, which accepts a GraphicsOutput as the first parameter.
Definition at line 133 of file graphicsEngine.I.
References FrameBufferProperties::get_default(), GraphicsStateGuardian::get_pipe, make_output(), and WindowProperties::size().
◆ make_output()
| GraphicsOutput * GraphicsEngine::make_output | ( | GraphicsPipe * | pipe, |
| const std::string & | name, | ||
| int | sort, | ||
| const FrameBufferProperties & | fb_prop, | ||
| const WindowProperties & | win_prop, | ||
| int | flags, | ||
| GraphicsStateGuardian * | gsg = nullptr, |
||
| GraphicsOutput * | host = nullptr |
||
| ) |
Creates a new window (or buffer) and returns it.
The GraphicsEngine becomes the owner of the window, it will persist at least until remove_window() is called later.
If a null pointer is supplied for the gsg, then this routine will create a new gsg.
This routine is only called from the app thread.
Definition at line 253 of file graphicsEngine.cxx.
References GraphicsOutput::get_gsg, GraphicsOutput::get_host(), WindowProperties::get_x_size(), WindowProperties::get_y_size(), WindowProperties::has_size, GraphicsStateGuardian::is_valid, GraphicsOutput::is_valid(), GraphicsStateGuardian::needs_reset(), and open_windows().
Referenced by make_buffer(), and make_parasite().
◆ make_parasite()
|
inline |
Syntactic shorthand for make_buffer.
Definition at line 155 of file graphicsEngine.I.
References GraphicsOutput::get_gsg, GraphicsOutput::get_pipe, make_output(), and WindowProperties::size().
◆ open_windows()
| void GraphicsEngine::open_windows | ( | ) |
Fully opens (or closes) any windows that have recently been requested open or closed, without rendering any frames.
It is not necessary to call this explicitly, since windows will be automatically opened or closed when the next frame is rendered, but you may call this if you want your windows now without seeing a frame go by.
Definition at line 955 of file graphicsEngine.cxx.
References GraphicsThreadingModel::get_cull_name(), GraphicsThreadingModel::get_cull_sorting(), GraphicsThreadingModel::get_cull_stage(), GraphicsThreadingModel::get_draw_name(), GraphicsThreadingModel::get_draw_stage(), GraphicsOutput::get_pipe, and ordered_vector< Key, Compare, Vector >::push_back().
Referenced by make_output(), and render_frame().
◆ ready_flip()
| void GraphicsEngine::ready_flip | ( | ) |
Waits for all the threads that started drawing their last frame to finish drawing.
Returns when all threads have actually finished drawing, as opposed to 'sync_frame' we seems to return once all draw calls have been submitted. Calling 'flip_frame' after this function should immediately cause a buffer flip. This function will only work in opengl right now, for all other graphics pipelines it will simply return immediately. In opengl it's a bit of a hack: it will attempt to read a single pixel from the frame buffer to force the graphics card to finish drawing before it returns
Definition at line 1072 of file graphicsEngine.cxx.
◆ remove_all_windows()
| void GraphicsEngine::remove_all_windows | ( | ) |
Removes and closes all windows from the engine.
This also cleans up and terminates any threads that have been started to service those windows.
Definition at line 585 of file graphicsEngine.cxx.
References ordered_vector< Key, Compare, Vector >::swap().
Referenced by ~GraphicsEngine().
◆ remove_window()
| bool GraphicsEngine::remove_window | ( | GraphicsOutput * | window | ) |
Removes the indicated window or offscreen buffer from the set of windows that will be processed when render_frame() is called.
This also closes the window if it is open, and removes the window from its GraphicsPipe, allowing the window to be destructed if there are no other references to it. (However, the window may not be actually closed until next frame, if it is controlled by a sub-thread.)
The return value is true if the window was removed, false if it was not found.
Unlike remove_all_windows(), this function does not terminate any of the threads that may have been started to service this window; they are left running (since you might open a new window later on these threads). If your intention is to clean up before shutting down, it is better to call remove_all_windows() then to call remove_window() one at a time.
Definition at line 516 of file graphicsEngine.cxx.
◆ render_frame()
| void GraphicsEngine::render_frame | ( | ) |
Renders the next frame in all the registered windows, and flips all of the frame buffers.
Definition at line 694 of file graphicsEngine.cxx.
References BamCache::consider_flush_global_index(), ClockObject::get_frame_count, ClockObject::get_global_clock(), and open_windows().
◆ reset_all_windows()
| void GraphicsEngine::reset_all_windows | ( | bool | swapchain | ) |
Resets the framebuffer of the current window.
This is currently used by DirectX 8 only. It calls a reset_window function on each active window to release/create old/new framebuffer
Definition at line 650 of file graphicsEngine.cxx.
References ordered_vector< Key, Compare, Vector >::begin(), ordered_vector< Key, Compare, Vector >::end(), and GraphicsOutput::reset_window().
◆ sync_frame()
| void GraphicsEngine::sync_frame | ( | ) |
Waits for all the threads that started drawing their last frame to finish drawing.
The windows are not yet flipped when this returns; see also flip_frame(). It is not usually necessary to call this explicitly, unless you need to see the previous frame right away.
Definition at line 1051 of file graphicsEngine.cxx.
◆ texture_uploaded()
| void GraphicsEngine::texture_uploaded | ( | Texture * | tex | ) |
This method is called by the GraphicsStateGuardian after a texture has been successfully uploaded to graphics memory.
It is intended as a callback so the texture can release its RAM image, if _keep_ram_image is false.
Normally, this is not called directly except by the GraphicsStateGuardian. It will be called in the draw thread.
Definition at line 1250 of file graphicsEngine.cxx.
References Texture::get_image_modified.
Member Data Documentation
◆ get_auto_flip
|
inline |
Returns the current setting for the auto-flip flag.
See set_auto_flip.
Definition at line 67 of file graphicsEngine.h.
◆ get_default_loader
|
inline |
Returns the Loader object that will be assigned to every GSG created with this GraphicsEngine.
See GraphicsStateGuardian::set_loader().
Definition at line 75 of file graphicsEngine.h.
◆ get_num_windows
| int GraphicsEngine::get_num_windows |
Returns the number of windows (or buffers) managed by the engine.
Definition at line 103 of file graphicsEngine.h.
◆ get_portal_cull
|
inline |
Returns the current setting for the portal culling flag.
Definition at line 71 of file graphicsEngine.h.
◆ get_render_lock
|
inline |
Returns a ReMutex object that is held by the GraphicsEngine during the entire call to render_frame().
While you hold this lock you can be confident that no part of the frame will be rendered (at least by the app thread).
Definition at line 63 of file graphicsEngine.h.
◆ get_threading_model
| GraphicsThreadingModel GraphicsEngine::get_threading_model |
Returns the threading model that will be applied to future objects.
Definition at line 60 of file graphicsEngine.h.
◆ get_window
| GraphicsOutput * GraphicsEngine::get_window |
Returns the nth window or buffers managed by the engine, in sorted order.
Definition at line 103 of file graphicsEngine.h.
◆ set_auto_flip
|
inline |
Set this flag true to indicate the GraphicsEngine should automatically cause windows to sync and flip as soon as they have finished drawing, rather than waiting for all of the windows to finish drawing first so they can flip together.
This only affects the timing of when the flip occurs. If this is true (the default), the flip occurs before render_frame() returns. If this is false, the flip occurs whenever flip_frame() is called, or at the beginning of the next call to render_frame(), if flip_frame() is never called.
Definition at line 67 of file graphicsEngine.h.
◆ set_default_loader
|
inline |
Sets the Loader object that will be assigned to every GSG created with this GraphicsEngine.
See GraphicsStateGuardian::set_loader().
Definition at line 75 of file graphicsEngine.h.
◆ set_portal_cull
|
inline |
Set this flag true to indicate the GraphicsEngine should start portal culling.
Definition at line 71 of file graphicsEngine.h.
◆ set_threading_model
| void GraphicsEngine::set_threading_model |
Specifies how future objects created via make_gsg(), make_buffer(), and make_window() will be threaded.
This does not affect any already-created objects.
Definition at line 60 of file graphicsEngine.h.
Referenced by GraphicsEngine().
The documentation for this class was generated from the following files:
- panda/src/display/graphicsEngine.h
- panda/src/display/graphicsEngine.cxx
- panda/src/display/graphicsEngine.I
