Panda3D
 All Classes Functions Variables Enumerations
config_display.cxx
1 // Filename: config_display.cxx
2 // Created by: drose (06Oct99)
3 //
4 ////////////////////////////////////////////////////////////////////
5 //
6 // PANDA 3D SOFTWARE
7 // Copyright (c) Carnegie Mellon University. All rights reserved.
8 //
9 // All use of this software is subject to the terms of the revised BSD
10 // license. You should have received a copy of this license along
11 // with this source code in a file named "LICENSE."
12 //
13 ////////////////////////////////////////////////////////////////////
14 
15 #include "config_display.h"
16 #include "callbackGraphicsWindow.h"
17 #include "displayRegion.h"
18 #include "displayRegionCullCallbackData.h"
19 #include "displayRegionDrawCallbackData.h"
20 #include "standardMunger.h"
21 #include "graphicsStateGuardian.h"
22 #include "graphicsPipe.h"
23 #include "graphicsOutput.h"
24 #include "graphicsBuffer.h"
25 #include "graphicsWindow.h"
26 #include "graphicsDevice.h"
27 #include "graphicsWindowProcCallbackData.h"
28 #include "nativeWindowHandle.h"
29 #include "parasiteBuffer.h"
30 #include "pandaSystem.h"
31 #include "stereoDisplayRegion.h"
32 #include "subprocessWindow.h"
33 #include "windowHandle.h"
34 
35 ConfigureDef(config_display);
36 NotifyCategoryDef(display, "");
37 NotifyCategoryDef(gsg, display_cat);
38 
39 ConfigureFn(config_display) {
40  init_libdisplay();
41 }
42 
43 ConfigVariableBool view_frustum_cull
44 ("view-frustum-cull", true,
45  PRC_DESC("This is normally true; set it false to disable view-frustum culling "
46  "(primarily useful for debugging)."));
47 
48 ConfigVariableBool pstats_unused_states
49 ("pstats-unused-states", false,
50  PRC_DESC("Set this true to show the number of unused states in the pstats "
51  "graph for TransformState and RenderState counts. This adds a bit "
52  "of per-frame overhead to count these things up."));
53 
54 
55 // Warning! The code that uses this is currently experimental and
56 // incomplete, and will almost certainly crash! Do not set
57 // threading-model to anything other than its default of a
58 // single-threaded model unless you are developing Panda's threading
59 // system!
60 ConfigVariableString threading_model
61 ("threading-model", "",
62  PRC_DESC("This is the default threading model to use for new windows. Use "
63  "empty string for single-threaded, or something like \"cull/draw\" for "
64  "a 3-stage pipeline. See GraphicsEngine::set_threading_model(). "
65  "EXPERIMENTAL and incomplete, do not use this!"));
66 
67 ConfigVariableBool allow_nonpipeline_threads
68 ("allow-nonpipeline-threads", false,
69  PRC_DESC("This variable should only be set true for debugging or development "
70  "purposes. When true, the threading-model variable may specify "
71  "a threaded pipeline mode, even if pipelining is not compiled in. "
72  "This will certainly result in erroneous behavior, and quite likely "
73  "will cause a crash. Do not set this unless you know what you "
74  "are doing."));
75 
76 ConfigVariableBool auto_flip
77 ("auto-flip", false,
78  PRC_DESC("This indicates the initial setting of the auto-flip flag. Set it "
79  "true to cause render_frame() to flip all the windows "
80  "before it returns (in single-threaded mode only), or false to wait "
81  "until an explicit call to flip_frame() or the next "
82  "render_frame(). Setting it true gets more immediate response "
83  "time, while setting it false can get a better frame rate as more "
84  "is achieved in parallel with the graphics card."));
85 
86 ConfigVariableBool sync_flip
87 ("sync-flip", false,
88  PRC_DESC("Set this true to attempt to flip all windows at the same time, "
89  "or false to flip each window as late as possible. Setting this "
90  "false can improve parallelization. This is a temporary "
91  "variable; it will later be replaced with a more explicit control "
92  "over synchronizing window flip."));
93 
94 ConfigVariableBool yield_timeslice
95 ("yield-timeslice", false,
96  PRC_DESC("Set this true to yield the timeslice at the end of the frame to be "
97  "more polite to other applications that are trying to run."));
98 
99 ConfigVariableDouble subprocess_window_max_wait
100 ("subprocess-window-max-wait", 0.2,
101  PRC_DESC("This is the amount of time, in seconds, that the SubprocessWindow will "
102  "wait in begin_flip for the parent process to remove the previously-rendered "
103  "frame. When this time is exceeded, the next frame will be rendered without "
104  "having flipped the previous one. This is designed to allow the Python "
105  "process some time to run even when the parent window is offscreen or minimized."));
106 
107 ConfigVariableString screenshot_filename
108 ("screenshot-filename", "%~p-%a-%b-%d-%H-%M-%S-%Y-%~f.%~e",
109  PRC_DESC("This specifies the filename pattern to be used to generate "
110  "screenshots captured via save_screenshot_default(). See "
111  "DisplayRegion::save_screenshot()."));
112 
113 ConfigVariableString screenshot_extension
114 ("screenshot-extension", "jpg",
115  PRC_DESC("This specifies the default filename extension (and therefore the "
116  "default image type) to be used for saving screenshots."));
117 
118 ConfigVariableBool prefer_texture_buffer
119 ("prefer-texture-buffer", true,
120  PRC_DESC("Set this true to make GraphicsOutput::make_texture_buffer() always "
121  "try to create an offscreen buffer supporting render-to-texture, "
122  "if the graphics card claims to be able to support this feature. "
123  "If the graphics card cannot support this feature, this option is "
124  "ignored. This is usually the fastest way to render "
125  "to a texture, and it presumably does not consume any additional "
126  "framebuffer memory over a copy-to-texture operation (since "
127  "the texture and the buffer share the "
128  "same memory)."));
129 
130 ConfigVariableBool prefer_parasite_buffer
131 ("prefer-parasite-buffer", false,
132  PRC_DESC("Set this true to make GraphicsOutput::make_texture_buffer() try to "
133  "create a ParasiteBuffer before it tries to create an offscreen "
134  "buffer (assuming it could not create a direct render buffer for "
135  "some reason). This may reduce your graphics card memory "
136  "requirements by sharing memory with the framebuffer, but it can "
137  "cause problems if the user subsequently resizes the window "
138  "smaller than the buffer."));
139 
140 ConfigVariableBool force_parasite_buffer
141 ("force-parasite-buffer", false,
142  PRC_DESC("Set this true to make GraphicsOutput::make_texture_buffer() really "
143  "strongly prefer ParasiteBuffers over conventional offscreen buffers. "
144  "With this set, it will create a ParasiteBuffer every time an offscreen "
145  "buffer is requested, even if this means reducing the buffer size to fit "
146  "within the window. The only exceptions are for buffers that, by their "
147  "nature, really cannot use ParasiteBuffers (like depth textures). You might "
148  "set this true if you don't trust your graphics driver's support for "
149  "offscreen buffers."));
150 
151 ConfigVariableBool prefer_single_buffer
152 ("prefer-single-buffer", true,
153  PRC_DESC("Set this true to make GraphicsOutput::make_render_texture() first "
154  "try to create a single-buffered offscreen buffer, before falling "
155  "back to a double-buffered one (or whatever kind the source window "
156  "has). This is true by default to reduce waste of framebuffer "
157  "memory, but you might get a performance benefit by setting it to "
158  "false (since in that case the buffer can share a graphics context "
159  "with the window)."));
160 
161 ConfigVariableInt max_texture_stages
162 ("max-texture-stages", -1,
163  PRC_DESC("Set this to a positive integer to limit the number of "
164  "texture stages reported by the GSG. This can be used to limit "
165  "the amount of multitexturing Panda will attempt to use. "
166  "If this is zero or less, the GSG will report its honest number "
167  "of texture stages, allowing Panda the full use of the graphics "
168  "card; if it is 1 or more, then Panda will never allow more than "
169  "this number of texture stages simultaneously, regardless of "
170  "what the GSG says it can do."));
171 
172 ConfigVariableInt max_color_targets
173 ("max-color-targets", -1,
174  PRC_DESC("Set this to a positive integer to limit the number of "
175  "color targets reported by the GSG. This can be used to limit "
176  "the amount of render targets Panda will attempt to use. "
177  "If this is zero or less, the GSG will report its honest number "
178  "of color targets, allowing Panda the full use of the graphics "
179  "card; if it is 1 or more, then Panda will never allow more than "
180  "this number of color targets simultaneously, regardless of "
181  "what the GSG says it can do."));
182 
183 ConfigVariableBool support_render_texture
184 ("support-render-texture", true,
185  PRC_DESC("Set this true allow use of the render-to-a-texture feature, if it "
186  "is supported by your graphics card. Without this enabled, "
187  "offscreen renders will be copied to a texture instead of directly "
188  "rendered there."));
189 
190 ConfigVariableBool support_rescale_normal
191 ("support-rescale-normal", true,
192  PRC_DESC("Set this true to allow use of the rescale-normal feature, if it "
193  "is supported by your graphics card. This allows lighting normals "
194  "to be uniformly counter-scaled, instead of re-normalized, "
195  "in the presence of a uniform scale, which should in principle be "
196  "a bit faster. This feature is only supported "
197  "by the OpenGL API."));
198 
199 ConfigVariableBool support_stencil
200 ("support-stencil", true,
201  PRC_DESC("Set this true to allow use of the stencil buffer, if it "
202  "is supported by your graphics card. If this is false, stencil "
203  "buffer support will not be enabled, even if it is supported. "
204  "Generally, only very old cards do not support some kind of "
205  "stencil buffer operations; but it is also not supported by "
206  "our tinydisplay renderer. "
207  "The main reason to set this false is to test your code in "
208  "the absence of stencil buffer support."));
209 
210 ConfigVariableBool copy_texture_inverted
211 ("copy-texture-inverted", false,
212  PRC_DESC("Set this true to indicate that the GSG in use will invert textures when "
213  "it performs a framebuffer-to-texture copy operation, or false to indicate "
214  "that it does the right thing. If this is not set, the default behavior is "
215  "determined by the GSG's internal logic."));
216 
217 ConfigVariableBool window_inverted
218 ("window-inverted", false,
219  PRC_DESC("Set this true to create all windows with the inverted flag set, so that "
220  "they will render upside-down and backwards. Normally this is useful only "
221  "for debugging."));
222 
223 ConfigVariableBool red_blue_stereo
224 ("red-blue-stereo", false,
225  PRC_DESC("Set this true to create windows with red-blue stereo mode enabled "
226  "by default, if the framebuffer does not support true stereo "
227  "rendering."));
228 
229 ConfigVariableString red_blue_stereo_colors
230 ("red-blue-stereo-colors", "red cyan",
231  PRC_DESC("This defines the color channels that are used for the left and "
232  "right eye, respectively, for red-blue-stereo mode. This should "
233  "be a two-word string, where each word is one of 'red', 'blue', "
234  "'green', 'cyan', 'magenta', 'yellow', or 'alpha', or a union "
235  "of two or more words separated by a vertical pipe (|)."));
236 
237 ConfigVariableBool side_by_side_stereo
238 ("side-by-side-stereo", false,
239  PRC_DESC("Set this true to create windows with side-by-side stereo mode enabled "
240  "by default, if the framebuffer does not support true stereo "
241  "rendering."));
242 
243 ConfigVariableDouble sbs_left_dimensions
244 ("sbs-left-dimensions", "0.0 0.5 0.0 1.0",
245  PRC_DESC("Defines the default region of the window that is used for the "
246  "left eye, when side-by-side stereo is enabled. This is a set of "
247  "four numbers, in the form left right top bottom, similar to a "
248  "normal DisplayRegion layout."));
249 
250 ConfigVariableDouble sbs_right_dimensions
251 ("sbs-right-dimensions", "0.5 1.0 0.0 1.0",
252  PRC_DESC("Defines the default region of the window that is used for the "
253  "right eye, when side-by-side stereo is enabled. This is a set of "
254  "four numbers, in the form left right top bottom, similar to a "
255  "normal DisplayRegion layout."));
256 
257 ConfigVariableBool swap_eyes
258 ("swap-eyes", false,
259  PRC_DESC("Set this true to reverse the left and right channel output of "
260  "stereo DisplayRegions."));
261 
262 ConfigVariableBool default_stereo_camera
263 ("default-stereo-camera", true,
264  PRC_DESC("When this is true, the default DisplayRegion created for "
265  "a window or buffer with the stereo property will be a "
266  "StereoDisplayRegion, which activates the stereo properties of "
267  "the camera lens, and enables stereo. Set this false to "
268  "require StereoDisplayRegions to be created explicitly."));
269 
270 ConfigVariableBool color_scale_via_lighting
271 ("color-scale-via-lighting", true,
272  PRC_DESC("When this is true, Panda will try to implement ColorAttribs and "
273  "ColorScaleAttribs using the lighting interface, by "
274  "creating a default material and/or an ambient light if "
275  "necessary, even if lighting is ostensibly disabled. This "
276  "avoids the need to munge the vertex data to change each vertex's "
277  "color. Set this false to avoid this trickery, so that lighting "
278  "is only enabled when the application specifically enables "
279  "it. See also alpha-scale-via-texture."));
280 
281 ConfigVariableBool alpha_scale_via_texture
282 ("alpha-scale-via-texture", true,
283  PRC_DESC("When this is true, Panda will try to implement "
284  "ColorScaleAttribs that affect alpha by "
285  "creating an additional Texture layer over the geometry "
286  "with a uniform alpha scale applied everywhere, if there "
287  "is at least one available Texture slot available on the "
288  "multitexture pipeline. Set this false to avoid this "
289  "trickery, so that texturing is only enabled when the "
290  "application specifically enables it. See also "
291  "color-scale-via-lighting."));
292 
293 ConfigVariableBool allow_incomplete_render
294 ("allow-incomplete-render", true,
295  PRC_DESC("When this is true, the frame may be rendered even if some of the "
296  "geometry in the scene has been paged out, or if the textures are "
297  "unavailable. The nonresident geometry and textures will be "
298  "rendered as soon as they can be read from disk, "
299  "which may be several frames in the future. When this is false, "
300  "geometry is always paged in immediately when needed, holding up "
301  "the frame render if necessary."));
302 
303 ConfigVariableInt win_size
304 ("win-size", "800 600",
305  PRC_DESC("This is the default size at which to open a new window. This "
306  "replaces the deprecated win-width and win-height variables."));
307 
308 ConfigVariableInt win_origin
309 ("win-origin", "",
310  PRC_DESC("This is the default position at which to open a new window. This "
311  "replaces the deprecated win-origin-x and win-origin-y variables. "
312  "A window coordinate of -1 means to choose a default value, "
313  "whereas -2 means to center the window on the screen."));
314 
315 ConfigVariableBool fullscreen
316 ("fullscreen", false);
317 
318 ConfigVariableBool undecorated
319 ("undecorated", false,
320  PRC_DESC("This specifies the default value of the 'undecorated' window "
321  "property. When this is true, the default window is created "
322  "without a title bar or resizable border."));
323 
324 ConfigVariableBool win_fixed_size
325 ("win-fixed-size", false,
326  PRC_DESC("This specifies the default value of the 'fixed_size' window "
327  "property. When this is true, the default window is created "
328  "without a resizable border."));
329 
330 ConfigVariableBool cursor_hidden
331 ("cursor-hidden", false);
332 
333 ConfigVariableFilename icon_filename
334 ("icon-filename", "");
335 
336 ConfigVariableFilename cursor_filename
337 ("cursor-filename", "");
338 
340 ("z-order", WindowProperties::Z_normal);
341 
342 ConfigVariableString window_title
343 ("window-title", "Panda");
344 
345 ConfigVariableInt parent_window_handle
346 ("parent-window-handle", 0,
347  PRC_DESC("The window handle of the parent window to attach the Panda window "
348  "to, for the purposes of creating an embedded window. This is "
349  "an HWND on Windows, or the NSWindow pointer or XWindow pointer "
350  "converted to an integer, on OSX and X11."));
351 
352 ConfigVariableBool win_unexposed_draw
353 ("win-unexposed-draw", true,
354  PRC_DESC("Specifies the default setting of GraphicsWindow::set_unexposed_draw(). "
355  "See that method for more information."));
356 
357 ConfigVariableFilename subprocess_window
358 ("subprocess-window", "",
359  PRC_DESC("The filename of a SubprocessWindowBuffer's temporary mmap file, "
360  "used for opening a window in a child process and rendering "
361  "to a different window in the parent process. "
362  "This is specifically used for OSX when the plugin is compiled, "
363  "and is not used or needed in other environments. See "
364  "WindowProperties::set_subprocess_window()."));
365 
366 ConfigVariableString framebuffer_mode
367 ("framebuffer-mode", "",
368  PRC_DESC("No longer has any effect. Do not use."));
369 
370 ConfigVariableBool framebuffer_hardware
371 ("framebuffer-hardware", true,
372  PRC_DESC("True if FM_hardware should be added to the default framebuffer "
373  "properties, which requests a hardware-accelerated display."));
374 ConfigVariableBool framebuffer_software
375 ("framebuffer-software", false,
376  PRC_DESC("True if FM_software should be added to the default framebuffer "
377  "properties, which requests a software-only display."));
378 ConfigVariableBool framebuffer_multisample
379 ("framebuffer-multisample", false,
380  PRC_DESC("True if FM_multisample should be added to the default framebuffer "
381  "properties, which requests a multisample-capable display, if "
382  "possible. This can be used to implement full-screen "
383  "antialiasing."));
384 ConfigVariableBool framebuffer_depth
385 ("framebuffer-depth", true,
386  PRC_DESC("True if FM_depth should be added to the default framebuffer "
387  "properties, which requests a depth buffer."));
388 ConfigVariableBool framebuffer_alpha
389 ("framebuffer-alpha", true,
390  PRC_DESC("True if FM_alpha should be added to the default framebuffer "
391  "properties, which requests an alpha channel if possible."));
392 ConfigVariableBool framebuffer_stencil
393 ("framebuffer-stencil", false,
394  PRC_DESC("True if FM_stencil should be added to the default framebuffer "
395  "properties, which requests an stencil buffer if possible."));
396 ConfigVariableBool framebuffer_accum
397 ("framebuffer-accum", false,
398  PRC_DESC("True if FM_accum should be added to the default framebuffer "
399  "properties, which requests an accumulator buffer if possible."));
400 ConfigVariableBool framebuffer_stereo
401 ("framebuffer-stereo", false,
402  PRC_DESC("True if FM_stereo should be added to the default framebuffer "
403  "properties, which requests a stereo-capable display, if "
404  "supported by the graphics driver."));
405 ConfigVariableBool framebuffer_srgb
406 ("framebuffer-srgb", false,
407  PRC_DESC("Set this to request an sRGB framebuffer, which will "
408  "convert all values to linear space before blending. This "
409  "means that the output will be properly gamma-corrected, as "
410  "long as all the input textures are either converted from "
411  "original sRGB to linear or sRGB textures are used."));
412 ConfigVariableBool framebuffer_float
413 ("framebuffer-float", false,
414  PRC_DESC("Set this to request a framebuffer that uses floating-point "
415  "storage for the color channel."));
416 
417 ConfigVariableInt depth_bits
418 ("depth-bits", 0,
419  PRC_DESC("The minimum number of depth buffer bits requested."));
420 ConfigVariableInt color_bits
421 ("color-bits", "",
422  PRC_DESC("The minimum number of total color buffer bits requested. If you "
423  "specify only one value, it will represent the total value for the "
424  "red, green and blue channels, and indicates you don't care how the "
425  "bits are divided up among the red, green and blue channels. If "
426  "you specify three values, it represents three separate red, green "
427  "and blue bit requirements."));
428 ConfigVariableInt alpha_bits
429 ("alpha-bits", 0,
430  PRC_DESC("The minimum number of alpha buffer bits requested."));
431 ConfigVariableInt stencil_bits
432 ("stencil-bits", 0,
433  PRC_DESC("The minimum number of stencil buffer bits requested."));
434 ConfigVariableInt accum_bits
435 ("accum-bits", 0,
436  PRC_DESC("The minimum number of accumulator buffer bits requested."));
437 ConfigVariableInt multisamples
438 ("multisamples", 0,
439  PRC_DESC("The minimum number of samples requested."));
440 ConfigVariableInt back_buffers
441 ("back-buffers", 1,
442  PRC_DESC("The default number of back buffers requested."));
443 
444 ConfigVariableDouble pixel_zoom
445 ("pixel-zoom", 1.0,
446  PRC_DESC("The default pixel_zoom factor for new windows."));
447 
448 ConfigVariableColor background_color
449 ("background-color", "0.41 0.41 0.41 0.0",
450  PRC_DESC("Specifies the rgb(a) value of the default background color for a "
451  "new window or offscreen buffer."));
452 
453 ConfigVariableBool sync_video
454 ("sync-video", true,
455  PRC_DESC("Configure this true to request the rendering to sync to the video "
456  "refresh, or false to let your frame rate go as high as it can, "
457  "irrespective of the video refresh. Usually you want this true, "
458  "but it may be useful to set it false during development for a "
459  "cheesy estimate of scene complexity. Some drivers may ignore "
460  "this request."));
461 
462 ConfigVariableBool basic_shaders_only
463 ("basic-shaders-only", false,
464  PRC_DESC("Set this to true if you aren't interested in shader model three "
465  "and beyond. Setting this flag will cause panda to disable "
466  "bleeding-edge shader functionality which tends to be unreliable "
467  "or broken. At some point, when functionality that is currently "
468  "flaky becomes reliable, we may expand the definition of what "
469  "constitutes 'basic' shaders."));
470 
471 ////////////////////////////////////////////////////////////////////
472 // Function: init_libdisplay
473 // Description: Initializes the library. This must be called at
474 // least once before any of the functions or classes in
475 // this library can be used. Normally it will be
476 // called by the static initializers and need not be
477 // called explicitly, but special cases exist.
478 ////////////////////////////////////////////////////////////////////
479 void
480 init_libdisplay() {
481  static bool initialized = false;
482  if (initialized) {
483  return;
484  }
485  initialized = true;
486 
487  CallbackGraphicsWindow::init_type();
488  DisplayRegion::init_type();
489  DisplayRegionCullCallbackData::init_type();
490  DisplayRegionDrawCallbackData::init_type();
491  DisplayRegionPipelineReader::init_type();
492  GraphicsBuffer::init_type();
493  GraphicsDevice::init_type();
494  GraphicsOutput::init_type();
495  GraphicsPipe::init_type();
496  GraphicsStateGuardian::init_type();
497  GraphicsWindow::init_type();
498  GraphicsWindowProcCallbackData::init_type();
499  NativeWindowHandle::init_type();
500  ParasiteBuffer::init_type();
501  StandardMunger::init_type();
502  StereoDisplayRegion::init_type();
503 #ifdef SUPPORT_SUBPROCESS_WINDOW
504  SubprocessWindow::init_type();
505 #endif
506  WindowHandle::init_type();
507  WindowHandle::OSHandle::init_type();
508 
509 #if defined(HAVE_THREADS) && defined(DO_PIPELINING)
511  ps->add_system("pipelining");
512 #endif
513 }
static PandaSystem * get_global_ptr()
Returns the global PandaSystem object.
This class is used as a namespace to group several global properties of Panda.
Definition: pandaSystem.h:29
This is a convenience class to specialize ConfigVariable as a Filename type.
This is a convenience class to specialize ConfigVariable as a boolean type.
This is a convenience class to specialize ConfigVariable as a set of floating-point types representin...
void add_system(const string &system)
Intended for use by each subsystem to register itself at startup.
This is a convenience class to specialize ConfigVariable as a floating-point type.
This is a convenience class to specialize ConfigVariable as a string type.
This class specializes ConfigVariable as an enumerated type.
This is a convenience class to specialize ConfigVariable as an integer type.