Panda3D
graphicsOutput.h
Go to the documentation of this file.
1 /**
2  * PANDA 3D SOFTWARE
3  * Copyright (c) Carnegie Mellon University. All rights reserved.
4  *
5  * All use of this software is subject to the terms of the revised BSD
6  * license. You should have received a copy of this license along
7  * with this source code in a file named "LICENSE."
8  *
9  * @file graphicsOutput.h
10  * @author drose
11  * @date 2004-02-06
12  */
13 
14 #ifndef GRAPHICSOUTPUT_H
15 #define GRAPHICSOUTPUT_H
16 
17 #include "pandabase.h"
18 
19 #include "graphicsPipe.h"
20 #include "displayRegion.h"
21 #include "stereoDisplayRegion.h"
22 #include "graphicsStateGuardian.h"
23 #include "drawableRegion.h"
24 #include "renderBuffer.h"
25 #include "graphicsOutputBase.h"
26 #include "luse.h"
28 #include "pandaNode.h"
29 #include "pStatCollector.h"
30 #include "pnotify.h"
31 #include "lightMutex.h"
32 #include "filename.h"
33 #include "drawMask.h"
34 #include "pvector.h"
35 #include "weakPointerTo.h"
36 #include "nodePath.h"
37 #include "cycleData.h"
38 #include "cycleDataLockedReader.h"
39 #include "cycleDataReader.h"
40 #include "cycleDataWriter.h"
41 #include "pipelineCycler.h"
42 #include "updateSeq.h"
43 #include "asyncFuture.h"
44 
45 class PNMImage;
46 class GraphicsEngine;
47 
48 /**
49  * This is a base class for the various different classes that represent the
50  * result of a frame of rendering. The most common kind of GraphicsOutput is
51  * a GraphicsWindow, which is a real-time window on the desktop, but another
52  * example is GraphicsBuffer, which is an offscreen buffer.
53  *
54  * The actual rendering, and anything associated with the graphics context
55  * itself, is managed by the associated GraphicsStateGuardian (which might
56  * output to multiple GraphicsOutput objects).
57  *
58  * GraphicsOutputs are not actually writable to bam files, of course, but they
59  * may be passed as event parameters, so they inherit from
60  * TypedWritableReferenceCount instead of TypedReferenceCount for that
61  * convenience.
62  */
63 class EXPCL_PANDA_DISPLAY GraphicsOutput : public GraphicsOutputBase, public DrawableRegion {
64 protected:
66  GraphicsPipe *pipe,
67  const std::string &name,
68  const FrameBufferProperties &fb_prop,
69  const WindowProperties &win_prop, int flags,
71  GraphicsOutput *host,
72  bool default_stereo_flags);
73  GraphicsOutput(const GraphicsOutput &copy) = delete;
74  GraphicsOutput &operator = (const GraphicsOutput &copy) = delete;
75 
76 PUBLISHED:
77  enum RenderTextureMode {
78  RTM_none,
79 
80  // Try to render to the texture directly, but if that is not possible,
81  // fall back to RTM_copy_texture.
82  RTM_bind_or_copy,
83 
84  // Copy the image from the buffer to the texture every frame.
85  RTM_copy_texture,
86 
87  // Copy the image from the buffer to system RAM every frame.
88  RTM_copy_ram,
89 
90  // Copy the image from the buffer to the texture after a call to
91  // trigger_copy().
92  RTM_triggered_copy_texture,
93 
94  // Copy the image from the buffer to system RAM after a call to
95  // trigger_copy().
96  RTM_triggered_copy_ram,
97 
98  // Render directly to a layered texture, such as a cube map, 3D texture or
99  // 2D texture array. The layer that is being rendered to is selected by a
100  // geometry shader.
101  RTM_bind_layered,
102  };
103 
104  // There are many reasons to call begin_frameend_frame.
105  enum FrameMode {
106  FM_render, // We are rendering a frame.
107  FM_parasite, // We are rendering a frame of a parasite.
108  FM_refresh, // We are just refreshing the display or exposing the window.
109  };
110 
111  virtual ~GraphicsOutput();
112 
113  INLINE GraphicsStateGuardian *get_gsg() const;
114  INLINE GraphicsPipe *get_pipe() const;
115  INLINE GraphicsEngine *get_engine() const;
116  INLINE const std::string &get_name() const;
117  MAKE_PROPERTY(gsg, get_gsg);
118  MAKE_PROPERTY(pipe, get_pipe);
119  MAKE_PROPERTY(engine, get_engine);
120  MAKE_PROPERTY(name, get_name);
121 
122  INLINE int count_textures() const;
123  INLINE bool has_texture() const;
124  virtual INLINE Texture *get_texture(int i=0) const;
125  INLINE RenderTexturePlane get_texture_plane(int i=0) const;
126  INLINE RenderTextureMode get_rtm_mode(int i=0) const;
127  void clear_render_textures();
128  void add_render_texture(Texture *tex, RenderTextureMode mode,
129  RenderTexturePlane bitplane=RTP_COUNT);
130  void setup_render_texture(Texture *tex, bool allow_bind, bool to_ram);
131 
132  INLINE const LVecBase2i &get_size() const;
133  INLINE int get_x_size() const;
134  INLINE int get_y_size() const;
135  INLINE LVecBase2i get_fb_size() const;
136  INLINE int get_fb_x_size() const;
137  INLINE int get_fb_y_size() const;
138  INLINE LVecBase2i get_sbs_left_size() const;
139  INLINE int get_sbs_left_x_size() const;
140  INLINE int get_sbs_left_y_size() const;
141  INLINE LVecBase2i get_sbs_right_size() const;
142  INLINE int get_sbs_right_x_size() const;
143  INLINE int get_sbs_right_y_size() const;
144  INLINE bool has_size() const;
145  INLINE bool is_valid() const;
146  INLINE bool is_nonzero_size() const;
147 
148  MAKE_PROPERTY(size, get_size);
149  MAKE_PROPERTY(fb_size, get_fb_size);
150  MAKE_PROPERTY(sbs_left_size, get_sbs_left_size);
151  MAKE_PROPERTY(sbs_right_size, get_sbs_right_size);
152 
153  void set_active(bool active);
154  virtual bool is_active() const;
155  MAKE_PROPERTY(active, is_active, set_active);
156 
157  void set_one_shot(bool one_shot);
158  bool get_one_shot() const;
159  MAKE_PROPERTY(one_shot, get_one_shot, set_one_shot);
160 
161  void set_inverted(bool inverted);
162  INLINE bool get_inverted() const;
163  MAKE_PROPERTY(inverted, get_inverted, set_inverted);
164 
165  INLINE void set_swap_eyes(bool swap_eyes);
166  INLINE bool get_swap_eyes() const;
167  MAKE_PROPERTY(swap_eyes, get_swap_eyes, set_swap_eyes);
168 
169  INLINE void set_red_blue_stereo(bool red_blue_stereo,
170  unsigned int left_eye_color_mask,
171  unsigned int right_eye_color_mask);
172  INLINE bool get_red_blue_stereo() const;
173  INLINE unsigned int get_left_eye_color_mask() const;
174  INLINE unsigned int get_right_eye_color_mask() const;
175 
176  void set_side_by_side_stereo(bool side_by_side_stereo);
177  void set_side_by_side_stereo(bool side_by_side_stereo,
178  const LVecBase4 &sbs_left_dimensions,
179  const LVecBase4 &sbs_right_dimensions);
180  INLINE bool get_side_by_side_stereo() const;
181  INLINE const LVecBase4 &get_sbs_left_dimensions() const;
182  INLINE const LVecBase4 &get_sbs_right_dimensions() const;
183 
184  INLINE const FrameBufferProperties &get_fb_properties() const;
185  INLINE bool is_stereo() const;
186 
187  INLINE void clear_delete_flag();
188  bool get_delete_flag() const;
189 
190  virtual void set_sort(int sort);
191  INLINE int get_sort() const;
192  MAKE_PROPERTY(sort, get_sort, set_sort);
193 
194  INLINE void set_child_sort(int child_sort);
195  INLINE void clear_child_sort();
196  INLINE int get_child_sort() const;
197  MAKE_PROPERTY(child_sort, get_child_sort, set_child_sort);
198 
199  INLINE AsyncFuture *trigger_copy();
200 
201  INLINE DisplayRegion *make_display_region();
202  INLINE DisplayRegion *make_display_region(PN_stdfloat l, PN_stdfloat r, PN_stdfloat b, PN_stdfloat t);
203  DisplayRegion *make_display_region(const LVecBase4 &dimensions);
204  INLINE DisplayRegion *make_mono_display_region();
205  INLINE DisplayRegion *make_mono_display_region(PN_stdfloat l, PN_stdfloat r, PN_stdfloat b, PN_stdfloat t);
206  DisplayRegion *make_mono_display_region(const LVecBase4 &dimensions);
207  INLINE StereoDisplayRegion *make_stereo_display_region();
208  INLINE StereoDisplayRegion *make_stereo_display_region(PN_stdfloat l, PN_stdfloat r, PN_stdfloat b, PN_stdfloat t);
209  StereoDisplayRegion *make_stereo_display_region(const LVecBase4 &dimensions);
210  bool remove_display_region(DisplayRegion *display_region);
211  void remove_all_display_regions();
212 
213  INLINE DisplayRegion *get_overlay_display_region() const;
214  void set_overlay_display_region(DisplayRegion *display_region);
215 
216  int get_num_display_regions() const;
217  PT(DisplayRegion) get_display_region(int n) const;
218  MAKE_SEQ(get_display_regions, get_num_display_regions, get_display_region);
219  MAKE_SEQ_PROPERTY(display_regions, get_num_display_regions, get_display_region);
220 
221  int get_num_active_display_regions() const;
222  PT(DisplayRegion) get_active_display_region(int n) const;
223  MAKE_SEQ(get_active_display_regions, get_num_active_display_regions, get_active_display_region);
224  MAKE_SEQ_PROPERTY(active_display_regions, get_num_active_display_regions, get_active_display_region);
225 
226  GraphicsOutput *make_texture_buffer(
227  const std::string &name, int x_size, int y_size,
228  Texture *tex = nullptr, bool to_ram = false, FrameBufferProperties *fbp = nullptr);
229  GraphicsOutput *make_cube_map(const std::string &name, int size,
230  NodePath &camera_rig,
232  bool to_ram = false, FrameBufferProperties *fbp = nullptr);
233 
234  INLINE static Filename make_screenshot_filename(
235  const std::string &prefix = "screenshot");
236  INLINE Filename save_screenshot_default(
237  const std::string &prefix = "screenshot");
238  INLINE bool save_screenshot(
239  const Filename &filename, const std::string &image_comment = "");
240  INLINE bool get_screenshot(PNMImage &image);
241  INLINE PT(Texture) get_screenshot();
242 
243  NodePath get_texture_card();
244 
245  virtual bool share_depth_buffer(GraphicsOutput *graphics_output);
246  virtual void unshare_depth_buffer();
247 
248  virtual bool get_supports_render_texture() const;
249  MAKE_PROPERTY(supports_render_texture, get_supports_render_texture);
250 
251 PUBLISHED:
252  // These are not intended to be called directly by the user, but they're
253  // published anyway since they might occasionally be useful for low-level
254  // debugging.
255  virtual bool flip_ready() const;
256  virtual GraphicsOutput *get_host();
257 
258 public:
259  INLINE bool operator < (const GraphicsOutput &other) const;
260 
261  virtual void request_open();
262  virtual void request_close();
263 
264  virtual void set_close_now();
265  virtual void reset_window(bool swapchain);
266  virtual void clear_pipe();
267 
268  void set_size_and_recalc(int x, int y);
269 
270  // It is an error to call any of the following methods from any thread other
271  // than the draw thread. These methods are normally called by the
272  // GraphicsEngine.
273  virtual void clear(Thread *current_thread);
274  virtual bool begin_frame(FrameMode mode, Thread *current_thread);
275  virtual void end_frame(FrameMode mode, Thread *current_thread);
276 
277  void change_scenes(DisplayRegionPipelineReader *new_dr);
278  virtual void select_target_tex_page(int page);
279 
280  // These methods will be called within the app (main) thread.
281  virtual void begin_flip();
282  virtual void ready_flip();
283  virtual void end_flip();
284 
285  // It is an error to call any of the following methods from any thread other
286  // than the window thread. These methods are normally called by the
287  // GraphicsEngine.
288  virtual void process_events();
289 
290  INLINE PStatCollector &get_cull_window_pcollector();
291  INLINE PStatCollector &get_draw_window_pcollector();
292  INLINE PStatCollector &get_clear_window_pcollector();
293 
294 protected:
295  virtual void pixel_factor_changed();
296  void prepare_for_deletion();
297  void promote_to_copy_texture();
298  bool copy_to_textures();
299 
300  INLINE void begin_frame_spam(FrameMode mode);
301  INLINE void end_frame_spam(FrameMode mode);
302  INLINE void clear_cube_map_selection();
303  INLINE void trigger_flip();
304 
305  class CData;
306 
307 private:
308  PT(GeomVertexData) create_texture_card_vdata(int x, int y);
309 
310  DisplayRegion *add_display_region(DisplayRegion *display_region);
311  bool do_remove_display_region(DisplayRegion *display_region);
312 
313  INLINE void win_display_regions_changed();
314 
315  INLINE void determine_display_regions() const;
316  void do_determine_display_regions(CData *cdata);
317 
318  static unsigned int parse_color_mask(const std::string &word);
319 
320 protected:
321  PT(GraphicsStateGuardian) _gsg;
322  GraphicsEngine *_engine;
323  PT(GraphicsPipe) _pipe;
324  PT(GraphicsOutput) _host;
325  FrameBufferProperties _fb_properties;
326  bool _stereo;
327  std::string _name;
328  bool _flip_ready;
329  int _target_tex_page;
330  int _target_tex_view;
331  DisplayRegion *_prev_page_dr;
332  PT(GeomNode) _texture_card;
333  PT(AsyncFuture) _trigger_copy;
334 
335  class RenderTexture {
336  public:
337  PT(Texture) _texture;
338  RenderTexturePlane _plane;
339  RenderTextureMode _rtm_mode;
340  };
341  typedef pvector<RenderTexture> RenderTextures;
342 
343 private:
344  int _sort;
345  int _child_sort;
346  bool _got_child_sort;
347  unsigned int _internal_sort_index;
348 
349 protected:
350  bool _inverted;
351  bool _swap_eyes;
352  bool _red_blue_stereo;
353  unsigned int _left_eye_color_mask;
354  unsigned int _right_eye_color_mask;
355  bool _side_by_side_stereo;
356  LVecBase4 _sbs_left_dimensions;
357  LVecBase4 _sbs_right_dimensions;
358  bool _delete_flag;
359 
360  // These weak pointers are used to keep track of whether the buffer's bound
361  // Textures have been deleted or not. Until they have, we don't auto-close
362  // the buffer (since that would deallocate the memory associated with the
363  // texture).
364  pvector<WPT(Texture)> _hold_textures;
365 
366 protected:
367  LightMutex _lock;
368  // protects _display_regions.
369  PT(DisplayRegion) _overlay_display_region;
370  typedef pvector< PT(DisplayRegion) > TotalDisplayRegions;
371  TotalDisplayRegions _total_display_regions;
372  typedef pvector<DisplayRegion *> ActiveDisplayRegions;
373 
374  // This is the data that is associated with the GraphicsOutput that needs to
375  // be cycled every frame. Mostly we don't cycle this data, but we do cycle
376  // the textures list, and the active flag.
377  class EXPCL_PANDA_DISPLAY CData : public CycleData {
378  public:
379  CData();
380  CData(const CData &copy);
381 
382  virtual CycleData *make_copy() const;
383  virtual TypeHandle get_parent_type() const {
384  return GraphicsOutput::get_class_type();
385  }
386 
387  RenderTextures _textures;
388  UpdateSeq _textures_seq;
389  bool _active;
390  int _one_shot_frame;
391  ActiveDisplayRegions _active_display_regions;
392  bool _active_display_regions_stale;
393  };
394  PipelineCycler<CData> _cycler;
395  typedef CycleDataLockedReader<CData> CDLockedReader;
396  typedef CycleDataReader<CData> CDReader;
397  typedef CycleDataWriter<CData> CDWriter;
398  typedef CycleDataStageWriter<CData> CDStageWriter;
399 
400 protected:
401  int _creation_flags;
402  LVecBase2i _size;
403  bool _has_size;
404  bool _is_valid;
405  bool _is_nonzero_size;
406 
407  static PStatCollector _make_current_pcollector;
408  static PStatCollector _copy_texture_pcollector;
409  static PStatCollector _cull_pcollector;
410  static PStatCollector _draw_pcollector;
411  PStatCollector _cull_window_pcollector;
412  PStatCollector _draw_window_pcollector;
413  PStatCollector _clear_window_pcollector;
414 
415 public:
416  static TypeHandle get_class_type() {
417  return _type_handle;
418  }
419  static void init_type() {
420  GraphicsOutputBase::init_type();
421  register_type(_type_handle, "GraphicsOutput",
422  GraphicsOutputBase::get_class_type());
423  }
424  virtual TypeHandle get_type() const {
425  return get_class_type();
426  }
427  virtual TypeHandle force_init_type() {init_type(); return get_class_type();}
428 
429 private:
430  static TypeHandle _type_handle;
431 
432  friend class GraphicsPipe;
433  friend class GraphicsEngine;
434  friend class DisplayRegion;
435 };
436 
437 EXPCL_PANDA_DISPLAY std::ostream &operator << (std::ostream &out, GraphicsOutput::FrameMode mode);
438 
439 #include "graphicsOutput.I"
440 
441 #endif /* GRAPHICSOUTPUT_H */
UpdateSeq
This is a sequence number that increments monotonically.
Definition: updateSeq.h:37
nodePath.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
FrameBufferProperties
A container for the various kinds of properties we might ask to have on a graphics frameBuffer before...
Definition: frameBufferProperties.h:26
pandaNode.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
CycleData
A single page of data maintained by a PipelineCycler.
Definition: cycleData.h:50
pvector< RenderTexture >
GeomVertexData
This defines the actual numeric vertex data stored in a Geom, in the structure defined by a particula...
Definition: geomVertexData.h:68
CycleData::get_parent_type
virtual TypeHandle get_parent_type() const
Returns the type of the container that owns the CycleData.
Definition: cycleData.cxx:76
pandabase.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
pvector.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
register_type
void register_type(TypeHandle &type_handle, const std::string &name)
This inline function is just a convenient way to call TypeRegistry::register_type(),...
Definition: register_type.I:22
stereoDisplayRegion.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
lightMutex.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
graphicsOutput.I
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
DisplayRegion
A rectangular subregion within a window for rendering into.
Definition: displayRegion.h:57
BitMask< uint32_t, 32 >
Texture
Represents a texture object, which is typically a single 2-d image but may also represent a 1-d or 3-...
Definition: texture.h:71
WindowProperties
A container for the various kinds of properties we might ask to have on a graphics window before we o...
Definition: windowProperties.h:29
filename.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
typedWritableReferenceCount.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
PandaNode::get_all_camera_mask
get_all_camera_mask
Returns a DrawMask that is appropriate for rendering to all cameras.
Definition: pandaNode.h:247
graphicsPipe.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
PNMImage
The name of this class derives from the fact that we originally implemented it as a layer on top of t...
Definition: pnmImage.h:58
LightMutex
This is a standard, non-reentrant mutex, similar to the Mutex class.
Definition: lightMutex.h:41
pnotify.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
AsyncFuture
This class represents a thread-safe handle to a promised future result of an asynchronous operation,...
Definition: asyncFuture.h:61
GraphicsEngine
This class is the main interface to controlling the render process.
Definition: graphicsEngine.h:53
TypeHandle
TypeHandle is the identifier used to differentiate C++ class types.
Definition: typeHandle.h:81
GeomNode
A node that holds Geom objects, renderable pieces of geometry.
Definition: geomNode.h:34
GraphicsOutput
This is a base class for the various different classes that represent the result of a frame of render...
Definition: graphicsOutput.h:63
displayRegion.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
StereoDisplayRegion
This is a special DisplayRegion wrapper that actually includes a pair of DisplayRegions internally: t...
Definition: stereoDisplayRegion.h:32
CycleDataWriter
This template class calls PipelineCycler::write() in the constructor and PipelineCycler::release_writ...
Definition: cycleDataWriter.h:34
cycleData.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
cycleDataLockedReader.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
luse.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
DrawableRegion
This is a base class for GraphicsWindow (actually, GraphicsOutput) and DisplayRegion,...
Definition: drawableRegion.h:29
CycleDataReader
This template class calls PipelineCycler::read_unlocked(), and then provides a transparent read-only ...
Definition: cycleDataReader.h:35
PStatCollector
A lightweight class that represents a single element that may be timed and/or counted via stats.
Definition: pStatCollector.h:43
cycleDataReader.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
GraphicsPipe
An object to create GraphicsOutputs that share a particular 3-D API.
Definition: graphicsPipe.h:52
CycleDataStageWriter
This class is similar to CycleDataWriter, except it allows writing to a particular stage of the pipel...
Definition: cycleDataStageWriter.h:31
pipelineCycler.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
drawMask.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
NodePath
NodePath is the fundamental system for disambiguating instances, and also provides a higher-level int...
Definition: nodePath.h:159
drawableRegion.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
GraphicsOutputBase
An abstract base class for GraphicsOutput, for all the usual reasons.
Definition: graphicsOutputBase.h:25
CycleDataLockedReader
This template class calls PipelineCycler::read() in the constructor and PipelineCycler::release_read(...
Definition: cycleDataLockedReader.h:40
weakPointerTo.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
asyncFuture.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
GraphicsStateGuardian
Encapsulates all the communication with a particular instance of a given rendering backend.
Definition: graphicsStateGuardian.h:65
cycleDataWriter.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
Thread
A thread; that is, a lightweight process.
Definition: thread.h:46
updateSeq.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
DisplayRegionPipelineReader
Encapsulates the data from a DisplayRegion, pre-fetched for one stage of the pipeline.
Definition: displayRegion.h:311
graphicsOutputBase.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
graphicsStateGuardian.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
PipelineCycler< CData >
Filename
The name of a file, such as a texture file or an Egg file.
Definition: filename.h:39
renderBuffer.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
pStatCollector.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.