GraphicsEngine
from panda3d.core import GraphicsEngine
- class GraphicsEngine
Bases:
ReferenceCount
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.
Inheritance diagram
- __init__(*args, **kwargs)
- addWindow()
C++ Interface: add_window(const GraphicsEngine self, 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.
*/
- add_window()
C++ Interface: add_window(const GraphicsEngine self, 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.
*/
- auto_flip
- default_loader
- dispatchCompute()
C++ Interface: dispatch_compute(const GraphicsEngine self, const LVecBase3i work_groups, const RenderState state, GraphicsStateGuardian gsg) dispatch_compute(const GraphicsEngine self, const LVecBase3i work_groups, const ShaderAttrib sattr, GraphicsStateGuardian gsg)
- /**
Version of dispatch_compute that takes a ShaderAttrib instead of a full
RenderState.
*/
- /**
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.
*/
- dispatch_compute()
C++ Interface: dispatch_compute(const GraphicsEngine self, const LVecBase3i work_groups, const RenderState state, GraphicsStateGuardian gsg) dispatch_compute(const GraphicsEngine self, const LVecBase3i work_groups, const ShaderAttrib sattr, GraphicsStateGuardian gsg)
- /**
Version of dispatch_compute that takes a ShaderAttrib instead of a full
RenderState.
*/
- /**
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.
*/
- extractShaderBufferData()
C++ Interface: extract_shader_buffer_data(const GraphicsEngine self, ShaderBuffer buffer, GraphicsStateGuardian gsg)
- /**
Asks the indicated GraphicsStateGuardian to retrieve the buffer memory
image of the indicated ShaderBuffer and return it.
This is mainly useful for debugging. It is a very slow call because it
introduces a pipeline stall both of Panda’s pipeline and the graphics
pipeline.
The return value is empty if some kind of error occurred.
*/
- extractTextureData()
C++ Interface: extract_texture_data(const GraphicsEngine self, 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.
*/
- extract_shader_buffer_data()
C++ Interface: extract_shader_buffer_data(const GraphicsEngine self, ShaderBuffer buffer, GraphicsStateGuardian gsg)
- /**
Asks the indicated GraphicsStateGuardian to retrieve the buffer memory
image of the indicated ShaderBuffer and return it.
This is mainly useful for debugging. It is a very slow call because it
introduces a pipeline stall both of Panda’s pipeline and the graphics
pipeline.
The return value is empty if some kind of error occurred.
*/
- extract_texture_data()
C++ Interface: extract_texture_data(const GraphicsEngine self, 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.
*/
- flipFrame()
C++ Interface: flip_frame(const GraphicsEngine self)
- /**
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.
*/
- flip_frame()
C++ Interface: flip_frame(const GraphicsEngine self)
- /**
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.
*/
- getAutoFlip()
C++ Interface: get_auto_flip(GraphicsEngine self)
- /**
Returns the current setting for the auto-flip flag. See set_auto_flip.
*/
- getDefaultLoader()
C++ Interface: get_default_loader(GraphicsEngine self)
- /**
Returns the Loader object that will be assigned to every GSG created with
this GraphicsEngine. See GraphicsStateGuardian::set_loader().
*/
- getNumWindows()
C++ Interface: get_num_windows(GraphicsEngine self)
- /**
Returns the number of windows (or buffers) managed by the engine.
*/
- getPortalCull()
C++ Interface: get_portal_cull(GraphicsEngine self)
- /**
Returns the current setting for the portal culling flag.
*/
- getRenderLock()
C++ Interface: get_render_lock(GraphicsEngine self)
- /**
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).
*/
- getThreadingModel()
C++ Interface: get_threading_model(GraphicsEngine self)
- /**
Returns the threading model that will be applied to future objects. See
set_threading_model().
*/
- getWindow()
C++ Interface: get_window(GraphicsEngine self, int n)
- /**
Returns the nth window or buffers managed by the engine, in sorted order.
*/
- getWindows()
- get_auto_flip()
C++ Interface: get_auto_flip(GraphicsEngine self)
- /**
Returns the current setting for the auto-flip flag. See set_auto_flip.
*/
- get_default_loader()
C++ Interface: get_default_loader(GraphicsEngine self)
- /**
Returns the Loader object that will be assigned to every GSG created with
this GraphicsEngine. See GraphicsStateGuardian::set_loader().
*/
- get_num_windows()
C++ Interface: get_num_windows(GraphicsEngine self)
- /**
Returns the number of windows (or buffers) managed by the engine.
*/
- get_portal_cull()
C++ Interface: get_portal_cull(GraphicsEngine self)
- /**
Returns the current setting for the portal culling flag.
*/
- get_render_lock()
C++ Interface: get_render_lock(GraphicsEngine self)
- /**
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).
*/
- get_threading_model()
C++ Interface: get_threading_model(GraphicsEngine self)
- /**
Returns the threading model that will be applied to future objects. See
set_threading_model().
*/
- get_window()
C++ Interface: get_window(GraphicsEngine self, int n)
- /**
Returns the nth window or buffers managed by the engine, in sorted order.
*/
- get_windows()
- isEmpty()
C++ Interface: is_empty(GraphicsEngine self)
- /**
Returns true if there are no windows or buffers managed by the engine,
false if there is at least one.
*/
- is_empty()
C++ Interface: is_empty(GraphicsEngine self)
- /**
Returns true if there are no windows or buffers managed by the engine,
false if there is at least one.
*/
- makeBuffer()
C++ Interface: make_buffer(const GraphicsEngine self, GraphicsOutput host, str name, int sort, int x_size, int y_size) make_buffer(const GraphicsEngine self, GraphicsStateGuardian gsg, str name, int sort, int x_size, int y_size)
// Syntactic shorthand versions of make_output
- /**
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.
*/
- /**
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.
*/
- makeOutput()
C++ Interface: make_output(const GraphicsEngine self, GraphicsPipe pipe, str name, int sort, const FrameBufferProperties fb_prop, const WindowProperties win_prop, int flags, GraphicsStateGuardian gsg, GraphicsOutput host)
- makeParasite()
C++ Interface: make_parasite(const GraphicsEngine self, GraphicsOutput host, str name, int sort, int x_size, int y_size)
- /**
Syntactic shorthand for make_buffer.
*/
- make_buffer()
C++ Interface: make_buffer(const GraphicsEngine self, GraphicsOutput host, str name, int sort, int x_size, int y_size) make_buffer(const GraphicsEngine self, GraphicsStateGuardian gsg, str name, int sort, int x_size, int y_size)
// Syntactic shorthand versions of make_output
- /**
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.
*/
- /**
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.
*/
- make_output()
C++ Interface: make_output(const GraphicsEngine self, GraphicsPipe pipe, str name, int sort, const FrameBufferProperties fb_prop, const WindowProperties win_prop, int flags, GraphicsStateGuardian gsg, GraphicsOutput host)
- make_parasite()
C++ Interface: make_parasite(const GraphicsEngine self, GraphicsOutput host, str name, int sort, int x_size, int y_size)
- /**
Syntactic shorthand for make_buffer.
*/
- openWindows()
C++ Interface: open_windows(const GraphicsEngine self)
- /**
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.
*/
- open_windows()
C++ Interface: open_windows(const GraphicsEngine self)
- /**
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.
*/
- portal_cull
- readyFlip()
C++ Interface: ready_flip(const GraphicsEngine self)
- /**
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
*/
- ready_flip()
C++ Interface: ready_flip(const GraphicsEngine self)
- /**
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
*/
- removeAllWindows()
C++ Interface: remove_all_windows(const GraphicsEngine self)
- /**
Removes and closes all windows from the engine. This also cleans up and
terminates any threads that have been started to service those windows.
*/
- removeWindow()
C++ Interface: remove_window(const GraphicsEngine self, 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.
*/
- remove_all_windows()
C++ Interface: remove_all_windows(const GraphicsEngine self)
- /**
Removes and closes all windows from the engine. This also cleans up and
terminates any threads that have been started to service those windows.
*/
- remove_window()
C++ Interface: remove_window(const GraphicsEngine self, 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.
*/
- renderFrame()
C++ Interface: render_frame(const GraphicsEngine self)
- /**
Renders the next frame in all the registered windows, and flips all of the
frame buffers.
*/
- render_frame()
C++ Interface: render_frame(const GraphicsEngine self)
- /**
Renders the next frame in all the registered windows, and flips all of the
frame buffers.
*/
- render_lock
- resetAllWindows()
C++ Interface: reset_all_windows(const GraphicsEngine self, 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
*/
- reset_all_windows()
C++ Interface: reset_all_windows(const GraphicsEngine self, 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
*/
- setAutoFlip()
C++ Interface: set_auto_flip(const GraphicsEngine self, bool 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.
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.
*/
- setDefaultLoader()
C++ Interface: set_default_loader(const GraphicsEngine self, Loader loader)
- /**
Sets the Loader object that will be assigned to every GSG created with this
GraphicsEngine. See GraphicsStateGuardian::set_loader().
*/
- setPortalCull()
C++ Interface: set_portal_cull(const GraphicsEngine self, bool value)
- /**
Set this flag true to indicate the GraphicsEngine should start portal
culling
*/
- setThreadingModel()
C++ Interface: set_threading_model(const GraphicsEngine self, const GraphicsThreadingModel threading_model)
- /**
Specifies how future objects created via make_gsg(), make_buffer(), and
make_output() will be threaded. This does not affect any already-created
objects.
*/
- set_auto_flip()
C++ Interface: set_auto_flip(const GraphicsEngine self, bool 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.
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.
*/
- set_default_loader()
C++ Interface: set_default_loader(const GraphicsEngine self, Loader loader)
- /**
Sets the Loader object that will be assigned to every GSG created with this
GraphicsEngine. See GraphicsStateGuardian::set_loader().
*/
- set_portal_cull()
C++ Interface: set_portal_cull(const GraphicsEngine self, bool value)
- /**
Set this flag true to indicate the GraphicsEngine should start portal
culling
*/
- set_threading_model()
C++ Interface: set_threading_model(const GraphicsEngine self, const GraphicsThreadingModel threading_model)
- /**
Specifies how future objects created via make_gsg(), make_buffer(), and
make_output() will be threaded. This does not affect any already-created
objects.
*/
- syncFrame()
C++ Interface: sync_frame(const GraphicsEngine self)
- /**
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.
*/
- sync_frame()
C++ Interface: sync_frame(const GraphicsEngine self)
- /**
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.
*/
- threading_model
- windows