Panda3D
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends

GraphicsEngine Class Reference

This class is the main interface to controlling the render process. More...

#include "graphicsEngine.h"

Inheritance diagram for GraphicsEngine:
ReferenceCount MemoryBase

List of all members.

Classes

class  LoadedTexture
class  RenderThread
class  WindowRenderer

Public Types

enum  ThreadState {
  TS_wait, TS_do_frame, TS_do_flip, TS_do_release,
  TS_do_windows, TS_terminate, TS_done
}

Public Member Functions

 GraphicsEngine (Pipeline *pipeline=NULL)
 Creates a new GraphicsEngine object.
 ~GraphicsEngine ()
 Gracefully cleans up the graphics engine and its related threads and windows.
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.
void flip_frame ()
 Waits for all the threads that started drawing their last frame to finish drawing, and then flips all the windows.
bool get_auto_flip () const
 Returns the current setting for the auto-flip flag.
Loaderget_default_loader () const
 Returns the Loader object that will be assigned to every GSG created with this GraphicsEngine.
int get_num_windows () const
 Returns the number of windows (or buffers) managed by the engine.
bool get_portal_cull () const
 Returns the current setting for the portal culling flag.
int get_ref_count () const
 Returns the current reference count.
GraphicsThreadingModel get_threading_model () const
 Returns the threading model that will be applied to future objects.
WeakReferenceListget_weak_list () const
 Returns the WeakReferenceList associated with this ReferenceCount object.
GraphicsOutputget_window (int n) const
 Returns the nth window or buffers managed by the engine, in sorted order.
bool has_weak_list () const
 Returns true if this particular ReferenceCount object has a WeakReferenceList created, false otherwise.
bool is_empty () const
 Returns true if there are no windows or buffers managed by the engine, false if there is at least one.
void local_object ()
 This function should be called, once, immediately after creating a new instance of some ReferenceCount-derived object on the stack.
GraphicsOutputmake_buffer (GraphicsOutput *host, const string &name, int sort, int x_size, int y_size)
 Syntactic shorthand for make_output.
GraphicsOutputmake_buffer (GraphicsStateGuardian *gsg, const string &name, int sort, int x_size, int y_size)
 Syntactic shorthand for make_output.
GraphicsOutputmake_output (GraphicsPipe *pipe, const string &name, int sort, const FrameBufferProperties &fb_prop, const WindowProperties &win_prop, int flags, GraphicsStateGuardian *gsg=NULL, GraphicsOutput *host=NULL)
 Creates a new window (or buffer) and returns it.
GraphicsOutputmake_parasite (GraphicsOutput *host, const string &name, int sort, int x_size, int y_size)
 Syntactic shorthand for make_buffer.
 MAKE_SEQ (get_windows, get_num_windows, get_window)
void open_windows ()
 Fully opens (or closes) any windows that have recently been requested open or closed, without rendering any frames.
void operator delete (void *ptr, void *)
void operator delete (void *ptr)
void operator delete[] (void *, void *)
void operator delete[] (void *ptr)
void * operator new (size_t size, void *ptr)
void * operator new (size_t size)
void * operator new[] (size_t size, void *ptr)
void * operator new[] (size_t size)
void ref () const
 Explicitly increments the reference count.
void remove_all_windows ()
 Removes and closes all windows from the engine.
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.
void render_frame ()
 Renders the next frame in all the registered windows, and flips all of the frame buffers.
void reset_all_windows (bool swapchain)
 Resets the framebuffer of the current window.
void set_auto_flip (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.
void set_default_loader (Loader *loader)
 Sets the Loader object that will be assigned to every GSG created with this GraphicsEngine.
void set_portal_cull (bool value)
 Set this flag true to indicate the GraphicsEngine should start portal culling.
void set_threading_model (const GraphicsThreadingModel &threading_model)
 Specifies how future objects created via make_gsg(), make_buffer(), and make_window() will be threaded.
void sync_frame ()
 Waits for all the threads that started drawing their last frame to finish drawing.
bool test_ref_count_integrity () const
 Does some easy checks to make sure that the reference count isn't completely bogus.
bool test_ref_count_nonzero () const
 Does some easy checks to make sure that the reference count isn't zero, or completely bogus.
void texture_uploaded (Texture *tex)
 This method is called by the GraphicsStateGuardian after a texture has been successfully uploaded to graphics memory.
virtual bool unref () const
 Explicitly decrements the reference count.
void weak_ref (WeakPointerToVoid *ptv)
 Adds the indicated PointerToVoid as a weak reference to this object.
void weak_unref (WeakPointerToVoid *ptv)
 Removes the indicated PointerToVoid as a weak reference to this object.

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.
static TypeHandle get_class_type ()
static GraphicsEngineget_global_ptr ()
static void init_type ()

Protected Member Functions

bool do_test_ref_count_integrity () const
 Does some easy checks to make sure that the reference count isn't completely bogus.
bool do_test_ref_count_nonzero () const
 Returns true if the reference count is nonzero, false otherwise.

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 57 of file graphicsEngine.h.


Constructor & Destructor Documentation

GraphicsEngine::GraphicsEngine ( Pipeline pipeline = NULL)

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 126 of file graphicsEngine.cxx.

References Pipeline::get_render_pipeline(), and set_threading_model().

GraphicsEngine::~GraphicsEngine ( )

Gracefully cleans up the graphics engine and its related threads and windows.

Definition at line 159 of file graphicsEngine.cxx.

References remove_all_windows().


Member Function Documentation

void GraphicsEngine::do_cull ( CullHandler cull_handler,
SceneSetup scene_setup,
GraphicsStateGuardian gsg,
Thread current_thread 
) [static]
bool ReferenceCount::do_test_ref_count_integrity ( ) const [protected, inherited]

Does some easy checks to make sure that the reference count isn't completely bogus.

Returns true if ok, false otherwise.

Reimplemented in NodeReferenceCount, CachedTypedWritableReferenceCount, and NodeCachedReferenceCount.

Definition at line 29 of file referenceCount.cxx.

Referenced by ReferenceCount::do_test_ref_count_nonzero(), and ReferenceCount::test_ref_count_integrity().

bool ReferenceCount::do_test_ref_count_nonzero ( ) const [protected, inherited]

Returns true if the reference count is nonzero, false otherwise.

Definition at line 56 of file referenceCount.cxx.

References ReferenceCount::do_test_ref_count_integrity().

Referenced by ReferenceCount::test_ref_count_nonzero().

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 1001 of file graphicsEngine.cxx.

References GraphicsStateGuardian::extract_texture_data(), GraphicsThreadingModel::get_draw_name(), and GraphicsStateGuardian::get_threading_model().

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 962 of file graphicsEngine.cxx.

References Thread::get_current_thread().

bool GraphicsEngine::get_auto_flip ( ) const [inline]

Returns the current setting for the auto-flip flag.

See set_auto_flip.

Definition at line 46 of file graphicsEngine.I.

Loader * GraphicsEngine::get_default_loader ( ) const [inline]

Returns the Loader object that will be assigned to every GSG created with this GraphicsEngine.

See GraphicsStateGuardian::set_loader().

Definition at line 97 of file graphicsEngine.I.

int GraphicsEngine::get_num_windows ( ) const

Returns the number of windows (or buffers) managed by the engine.

Definition at line 609 of file graphicsEngine.cxx.

References ordered_vector< Key, Compare >::size().

bool GraphicsEngine::get_portal_cull ( ) const [inline]

Returns the current setting for the portal culling flag.

Definition at line 71 of file graphicsEngine.I.

int ReferenceCount::get_ref_count ( ) const [inline, inherited]
GraphicsThreadingModel GraphicsEngine::get_threading_model ( ) const

Returns the threading model that will be applied to future objects.

See set_threading_model().

Definition at line 212 of file graphicsEngine.cxx.

Referenced by make_output().

WeakReferenceList * ReferenceCount::get_weak_list ( ) const [inline, inherited]

Returns the WeakReferenceList associated with this ReferenceCount object.

If there has never been a WeakReferenceList associated with this object, creates one now.

Definition at line 307 of file referenceCount.I.

Referenced by ReferenceCount::weak_ref().

GraphicsOutput * GraphicsEngine::get_window ( int  n) const

Returns the nth window or buffers managed by the engine, in sorted order.

Definition at line 620 of file graphicsEngine.cxx.

References ordered_vector< Key, Compare >::size().

bool ReferenceCount::has_weak_list ( ) const [inline, inherited]

Returns true if this particular ReferenceCount object has a WeakReferenceList created, false otherwise.

In general, this will be true if there was ever a WeakPointerTo created for this object (even if there is not any for it now).

Definition at line 294 of file referenceCount.I.

Referenced by ReferenceCount::weak_unref().

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 598 of file graphicsEngine.cxx.

References ordered_vector< Key, Compare >::empty().

void ReferenceCount::local_object ( ) [inline, inherited]

This function should be called, once, immediately after creating a new instance of some ReferenceCount-derived object on the stack.

This allows the object to be passed to functions that will increment and decrement the object's reference count temporarily, and it will prevent the object from being deleted (inappropriately), when the reference count returns to zero. It actually achieves this by setting a large positive value in the reference count field.

Definition at line 276 of file referenceCount.I.

Referenced by PGTop::cull_callback(), BoundingSphere::extend_by_hexahedron(), AsyncTaskManager::find_task(), AsyncTaskManager::find_tasks(), and AsyncTaskManager::find_tasks_matching().

GraphicsOutput * GraphicsEngine::make_buffer ( GraphicsOutput host,
const string &  name,
int  sort,
int  x_size,
int  y_size 
) [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 127 of file graphicsEngine.I.

References GraphicsOutput::get_gsg(), GraphicsOutput::get_pipe(), make_output(), and WindowProperties::size().

GraphicsOutput * GraphicsEngine::make_buffer ( GraphicsStateGuardian gsg,
const string &  name,
int  sort,
int  x_size,
int  y_size 
) [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 159 of file graphicsEngine.I.

References FrameBufferProperties::get_default(), GraphicsStateGuardian::get_pipe(), make_output(), and WindowProperties::size().

GraphicsOutput * GraphicsEngine::make_output ( GraphicsPipe pipe,
const string &  name,
int  sort,
const FrameBufferProperties fb_prop,
const WindowProperties win_prop,
int  flags,
GraphicsStateGuardian gsg = NULL,
GraphicsOutput host = NULL 
)
GraphicsOutput * GraphicsEngine::make_parasite ( GraphicsOutput host,
const string &  name,
int  sort,
int  x_size,
int  y_size 
) [inline]

Syntactic shorthand for make_buffer.

Definition at line 183 of file graphicsEngine.I.

References GraphicsOutput::get_gsg(), GraphicsOutput::get_pipe(), make_output(), and WindowProperties::size().

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 899 of file graphicsEngine.cxx.

References Thread::get_current_thread().

Referenced by make_output(), and render_frame().

void ReferenceCount::ref ( ) const [inline, inherited]

Explicitly increments the reference count.

User code should avoid using ref() and unref() directly, which can result in missed reference counts. Instead, let a PointerTo object manage the reference counting automatically.

This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it.

Definition at line 179 of file referenceCount.I.

References ReferenceCount::test_ref_count_integrity().

Referenced by CachedTypedWritableReferenceCount::cache_ref(), TypedWritable::decode_raw_from_bam_stream(), NodeCachedReferenceCount::node_ref(), NodeReferenceCount::node_ref(), BamCacheRecord::set_data(), CullableObject::set_draw_callback(), and ModelRoot::set_reference().

void GraphicsEngine::remove_all_windows ( )
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 463 of file graphicsEngine.cxx.

References ordered_vector< Key, Compare >::begin(), ordered_vector< Key, Compare >::end(), Thread::get_current_thread(), GraphicsStateGuardianBase::get_gsg(), GraphicsOutput::get_gsg(), GraphicsStateGuardian::get_prepared_objects(), and PreparedGraphicsObjects::release_all().

Referenced by make_output(), and GraphicsStateGuardian::remove_window().

void GraphicsEngine::render_frame ( )

Renders the next frame in all the registered windows, and flips all of the frame buffers.

Definition at line 636 of file graphicsEngine.cxx.

References ordered_vector< Key, Compare >::begin(), ClockObject::check_errors(), BamCache::consider_flush_index(), Thread::consider_yield(), Pipeline::cycle(), ordered_vector< Key, Compare >::end(), TransformState::flush_level(), CullTraverser::flush_level(), GeomCacheManager::flush_level(), CullableObject::flush_level(), RenderState::flush_level(), Thread::force_yield(), DisplayRegion::get_camera(), Thread::get_current_thread(), GraphicsOutput::get_delete_flag(), ClockObject::get_frame_count(), ClockObject::get_global_clock(), VertexDataPage::get_global_lru(), BamCache::get_global_ptr(), GeomVertexArrayData::get_independent_lru(), GraphicsOutput::get_num_active_display_regions(), TransformState::get_num_states(), RenderState::get_num_states(), RenderState::get_num_unused_states(), TransformState::get_num_unused_states(), VertexDataPage::get_pending_lru(), VertexDataPage::get_save_file(), Camera::get_scene(), GeomVertexArrayData::get_small_lru(), NodePath::get_top(), VertexDataSaveFile::get_total_file_size(), SimpleLru::get_total_size(), VertexDataSaveFile::get_used_file_size(), PStatClient::is_connected(), NodePath::is_empty(), Thread::is_true_threads(), GeomVertexArrayData::lru_epoch(), NodePath::node(), open_windows(), ordered_vector< Key, Compare >::push_back(), ordered_vector< Key, Compare >::size(), ordered_vector< Key, Compare >::swap(), and ClockObject::tick().

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 581 of file graphicsEngine.cxx.

References ordered_vector< Key, Compare >::begin(), ordered_vector< Key, Compare >::end(), and GraphicsOutput::reset_window().

Referenced by DXGraphicsStateGuardian9::reset_d3d_device(), and DXGraphicsStateGuardian8::reset_d3d_device().

void GraphicsEngine::set_auto_flip ( bool  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 33 of file graphicsEngine.I.

void GraphicsEngine::set_default_loader ( Loader loader) [inline]

Sets the Loader object that will be assigned to every GSG created with this GraphicsEngine.

See GraphicsStateGuardian::set_loader().

Definition at line 85 of file graphicsEngine.I.

void GraphicsEngine::set_portal_cull ( bool  value) [inline]

Set this flag true to indicate the GraphicsEngine should start portal culling.

Definition at line 59 of file graphicsEngine.I.

void GraphicsEngine::set_threading_model ( const GraphicsThreadingModel 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 177 of file graphicsEngine.cxx.

References GraphicsThreadingModel::is_single_threaded(), and Thread::is_threading_supported().

Referenced by GraphicsEngine().

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 943 of file graphicsEngine.cxx.

References Thread::get_current_thread().

bool ReferenceCount::test_ref_count_integrity ( ) const [inline, inherited]
bool ReferenceCount::test_ref_count_nonzero ( ) const [inline, inherited]

Does some easy checks to make sure that the reference count isn't zero, or completely bogus.

Returns true if ok, false otherwise.

Definition at line 252 of file referenceCount.I.

References ReferenceCount::do_test_ref_count_nonzero().

Referenced by CopyOnWritePointer::test_ref_count_nonzero().

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 1056 of file graphicsEngine.cxx.

References Texture::get_image_modified().

Referenced by DXTextureContext9::create_texture(), and DXTextureContext8::create_texture().

bool ReferenceCount::unref ( ) const [inline, virtual, inherited]

Explicitly decrements the reference count.

Note that the object will not be implicitly deleted by unref() simply because the reference count drops to zero. (Having a member function delete itself is problematic.) However, see the helper function unref_delete().

User code should avoid using ref() and unref() directly, which can result in missed reference counts. Instead, let a PointerTo object manage the reference counting automatically.

This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it.

The return value is true if the new reference count is nonzero, false if it is zero.

Reimplemented in GeomVertexArrayFormat, GeomVertexFormat, InternalName, RenderAttrib, RenderEffects, RenderState, and TransformState.

Definition at line 214 of file referenceCount.I.

References ReferenceCount::test_ref_count_integrity().

Referenced by CachedTypedWritableReferenceCount::cache_unref(), TypedWritable::decode_raw_from_bam_stream(), RenderEffect::finalize(), NodeCachedReferenceCount::node_unref(), NodeReferenceCount::node_unref(), TransformState::unref(), RenderState::unref(), RenderEffects::unref(), RenderAttrib::unref(), InternalName::unref(), GeomVertexFormat::unref(), and GeomVertexArrayFormat::unref().

void ReferenceCount::weak_ref ( WeakPointerToVoid ptv) [inline, inherited]

Adds the indicated PointerToVoid as a weak reference to this object.

Definition at line 321 of file referenceCount.I.

References WeakReferenceList::add_reference(), and ReferenceCount::get_weak_list().

void ReferenceCount::weak_unref ( WeakPointerToVoid ptv) [inline, inherited]

Removes the indicated PointerToVoid as a weak reference to this object.

It must have previously been added via a call to weak_ref().

Definition at line 334 of file referenceCount.I.

References WeakReferenceList::clear_reference(), and ReferenceCount::has_weak_list().


The documentation for this class was generated from the following files:
 All Classes Functions Variables Enumerations