Panda3D

config_display.cxx

00001 // Filename: config_display.cxx
00002 // Created by:  drose (06Oct99)
00003 //
00004 ////////////////////////////////////////////////////////////////////
00005 //
00006 // PANDA 3D SOFTWARE
00007 // Copyright (c) Carnegie Mellon University.  All rights reserved.
00008 //
00009 // All use of this software is subject to the terms of the revised BSD
00010 // license.  You should have received a copy of this license along
00011 // with this source code in a file named "LICENSE."
00012 //
00013 ////////////////////////////////////////////////////////////////////
00014 
00015 #include "config_display.h"
00016 #include "callbackGraphicsWindow.h"
00017 #include "displayRegion.h"
00018 #include "displayRegionCullCallbackData.h"
00019 #include "displayRegionDrawCallbackData.h"
00020 #include "standardMunger.h"
00021 #include "graphicsStateGuardian.h"
00022 #include "graphicsPipe.h"
00023 #include "graphicsOutput.h"
00024 #include "graphicsBuffer.h"
00025 #include "graphicsWindow.h"
00026 #include "graphicsDevice.h"
00027 #ifdef HAVE_PYTHON
00028 #include "pythonGraphicsWindowProc.h"
00029 #endif
00030 #include "graphicsWindowProcCallbackData.h"
00031 #include "nativeWindowHandle.h"
00032 #include "parasiteBuffer.h"
00033 #include "pandaSystem.h"
00034 #include "stereoDisplayRegion.h"
00035 #include "subprocessWindow.h"
00036 #include "windowHandle.h"
00037 
00038 ConfigureDef(config_display);
00039 NotifyCategoryDef(display, "");
00040 NotifyCategoryDef(gsg, display_cat);
00041 
00042 ConfigureFn(config_display) {
00043   init_libdisplay();
00044 }
00045 
00046 ConfigVariableBool view_frustum_cull
00047 ("view-frustum-cull", true,
00048  PRC_DESC("This is normally true; set it false to disable view-frustum culling "
00049           "(primarily useful for debugging)."));
00050 
00051 ConfigVariableBool pstats_unused_states
00052 ("pstats-unused-states", false,
00053  PRC_DESC("Set this true to show the number of unused states in the pstats "
00054           "graph for TransformState and RenderState counts.  This adds a bit "
00055           "of per-frame overhead to count these things up."));
00056 
00057 
00058 // Warning!  The code that uses this is currently experimental and
00059 // incomplete, and will almost certainly crash!  Do not set
00060 // threading-model to anything other than its default of a
00061 // single-threaded model unless you are developing Panda's threading
00062 // system!
00063 ConfigVariableString threading_model
00064 ("threading-model", "",
00065  PRC_DESC("This is the default threading model to use for new windows.  Use "
00066           "empty string for single-threaded, or something like \"cull/draw\" for "
00067           "a 3-stage pipeline.  See GraphicsEngine::set_threading_model(). "
00068           "EXPERIMENTAL and incomplete, do not use this!"));
00069 
00070 ConfigVariableBool allow_nonpipeline_threads
00071 ("allow-nonpipeline-threads", false,
00072  PRC_DESC("This variable should only be set true for debugging or development "
00073           "purposes.  When true, the threading-model variable may specify "
00074           "a threaded pipeline mode, even if pipelining is not compiled in.  "
00075           "This will certainly result in erroneous behavior, and quite likely "
00076           "will cause a crash.  Do not set this unless you know what you "
00077           "are doing."));
00078 
00079 ConfigVariableBool auto_flip
00080 ("auto-flip", false,
00081  PRC_DESC("This indicates the initial setting of the auto-flip flag.  Set it "
00082           "true to cause render_frame() to flip all the windows "
00083           "before it returns (in single-threaded mode only), or false to wait "
00084           "until an explicit call to flip_frame() or the next "
00085           "render_frame().  Setting it true gets more immediate response "
00086           "time, while setting it false can get a better frame rate as more "
00087           "is achieved in parallel with the graphics card."));
00088 
00089 ConfigVariableBool sync_flip
00090 ("sync-flip", false,
00091  PRC_DESC("Set this true to attempt to flip all windows at the same time, "
00092           "or false to flip each window as late as possible.  Setting this "
00093           "false can improve parallelization.  This is a temporary "
00094           "variable; it will later be replaced with a more explicit control "
00095           "over synchronizing window flip."));
00096 
00097 ConfigVariableBool yield_timeslice
00098 ("yield-timeslice", false,
00099  PRC_DESC("Set this true to yield the timeslice at the end of the frame to be "
00100           "more polite to other applications that are trying to run."));
00101 
00102 ConfigVariableDouble subprocess_window_max_wait
00103 ("subprocess-window-max-wait", 0.2,
00104  PRC_DESC("This is the amount of time, in seconds, that the SubprocessWindow will "
00105           "wait in begin_flip for the parent process to remove the previously-rendered "
00106           "frame.  When this time is exceeded, the next frame will be rendered without "
00107           "having flipped the previous one.  This is designed to allow the Python "
00108           "process some time to run even when the parent window is offscreen or minimized."));
00109 
00110 ConfigVariableString screenshot_filename
00111 ("screenshot-filename", "%~p-%a-%b-%d-%H-%M-%S-%Y-%~f.%~e",
00112  PRC_DESC("This specifies the filename pattern to be used to generate "
00113           "screenshots captured via save_screenshot_default().  See "
00114           "DisplayRegion::save_screenshot()."));
00115 
00116 ConfigVariableString screenshot_extension
00117 ("screenshot-extension", "jpg",
00118  PRC_DESC("This specifies the default filename extension (and therefore the "
00119           "default image type) to be used for saving screenshots."));
00120 
00121 ConfigVariableBool prefer_texture_buffer
00122 ("prefer-texture-buffer", true,
00123  PRC_DESC("Set this true to make GraphicsOutput::make_texture_buffer() always "
00124           "try to create an offscreen buffer supporting render-to-texture, "
00125           "if the graphics card claims to be able to support this feature.  "
00126           "If the graphics card cannot support this feature, this option is "
00127           "ignored.  This is usually the fastest way to render "
00128           "to a texture, and it presumably does not consume any additional "
00129           "framebuffer memory over a copy-to-texture operation (since "
00130           "the texture and the buffer share the "
00131           "same memory)."));
00132 
00133 ConfigVariableBool prefer_parasite_buffer
00134 ("prefer-parasite-buffer", false,
00135  PRC_DESC("Set this true to make GraphicsOutput::make_texture_buffer() try to "
00136           "create a ParasiteBuffer before it tries to create an offscreen "
00137           "buffer (assuming it could not create a direct render buffer for "
00138           "some reason).  This may reduce your graphics card memory "
00139           "requirements by sharing memory with the framebuffer, but it can "
00140           "cause problems if the user subsequently resizes the window "
00141           "smaller than the buffer."));
00142 
00143 ConfigVariableBool force_parasite_buffer
00144 ("force-parasite-buffer", false,
00145  PRC_DESC("Set this true to make GraphicsOutput::make_texture_buffer() really "
00146           "strongly prefer ParasiteBuffers over conventional offscreen buffers.  "
00147           "With this set, it will create a ParasiteBuffer every time an offscreen "
00148           "buffer is requested, even if this means reducing the buffer size to fit "
00149           "within the window.  The only exceptions are for buffers that, by their "
00150           "nature, really cannot use ParasiteBuffers (like depth textures).  You might "
00151           "set this true if you don't trust your graphics driver's support for "
00152           "offscreen buffers."));
00153 
00154 ConfigVariableBool prefer_single_buffer
00155 ("prefer-single-buffer", true,
00156  PRC_DESC("Set this true to make GraphicsOutput::make_render_texture() first "
00157           "try to create a single-buffered offscreen buffer, before falling "
00158           "back to a double-buffered one (or whatever kind the source window "
00159           "has).  This is true by default to reduce waste of framebuffer "
00160           "memory, but you might get a performance benefit by setting it to "
00161           "false (since in that case the buffer can share a graphics context "
00162           "with the window)."));
00163 
00164 ConfigVariableInt max_texture_stages
00165 ("max-texture-stages", -1,
00166  PRC_DESC("Set this to a positive integer to limit the number of "
00167           "texture stages reported by the GSG.  This can be used to limit "
00168           "the amount of multitexturing Panda will attempt to use.  "
00169           "If this is zero or less, the GSG will report its honest number "
00170           "of texture stages, allowing Panda the full use of the graphics "
00171           "card; if it is 1 or more, then Panda will never allow more than "
00172           "this number of texture stages simultaneously, regardless of "
00173           "what the GSG says it can do."));
00174 
00175 ConfigVariableBool support_render_texture
00176 ("support-render-texture", true,
00177  PRC_DESC("Set this true allow use of the render-to-a-texture feature, if it "
00178           "is supported by your graphics card.  Without this enabled, "
00179           "offscreen renders will be copied to a texture instead of directly "
00180           "rendered there."));
00181 
00182 ConfigVariableBool support_rescale_normal
00183 ("support-rescale-normal", true,
00184  PRC_DESC("Set this true to allow use of the rescale-normal feature, if it "
00185           "is supported by your graphics card.  This allows lighting normals "
00186           "to be uniformly counter-scaled, instead of re-normalized, "
00187           "in the presence of a uniform scale, which should in principle be "
00188           "a bit faster.  This feature is only supported "
00189           "by the OpenGL API."));
00190 
00191 ConfigVariableBool support_stencil
00192 ("support-stencil", true,
00193  PRC_DESC("Set this true to allow use of the stencil buffer, if it "
00194           "is supported by your graphics card.  If this is false, stencil "
00195           "buffer support will not be enabled, even if it is supported.  "
00196           "Generally, only very old cards do not support some kind of "
00197           "stencil buffer operations; but it is also not supported by "
00198           "our tinydisplay renderer.  "
00199           "The main reason to set this false is to test your code in "
00200           "the absence of stencil buffer support."));
00201 
00202 ConfigVariableBool copy_texture_inverted
00203 ("copy-texture-inverted", false,
00204  PRC_DESC("Set this true to indicate that the GSG in use will invert textures when "
00205           "it performs a framebuffer-to-texture copy operation, or false to indicate "
00206           "that it does the right thing.  If this is not set, the default behavior is "
00207           "determined by the GSG's internal logic."));
00208 
00209 ConfigVariableBool window_inverted
00210 ("window-inverted", false,
00211  PRC_DESC("Set this true to create all windows with the inverted flag set, so that "
00212           "they will render upside-down and backwards.  Normally this is useful only "
00213           "for debugging."));
00214 
00215 ConfigVariableBool red_blue_stereo
00216 ("red-blue-stereo", false,
00217  PRC_DESC("Set this true to create windows with red-blue stereo mode enabled "
00218           "by default, if the framebuffer does not support true stereo "
00219           "rendering."));
00220 
00221 ConfigVariableString red_blue_stereo_colors
00222 ("red-blue-stereo-colors", "red cyan",
00223  PRC_DESC("This defines the color channels that are used for the left and "
00224           "right eye, respectively, for red-blue-stereo mode.  This should "
00225           "be a two-word string, where each word is one of 'red', 'blue', "
00226           "'green', 'cyan', 'magenta', 'yellow', or 'alpha', or a union "
00227           "of two or more words separated by a vertical pipe (|)."));
00228 
00229 ConfigVariableBool side_by_side_stereo
00230 ("side-by-side-stereo", false,
00231  PRC_DESC("Set this true to create windows with side-by-side stereo mode enabled "
00232           "by default, if the framebuffer does not support true stereo "
00233           "rendering."));
00234 
00235 ConfigVariableDouble sbs_left_dimensions
00236 ("sbs-left-dimensions", "0.0 0.5 0.0 1.0",
00237  PRC_DESC("Defines the default region of the window that is used for the "
00238           "left eye, when side-by-side stereo is enabled.  This is a set of "
00239           "four numbers, in the form left right top bottom, similar to a "
00240           "normal DisplayRegion layout."));
00241 
00242 ConfigVariableDouble sbs_right_dimensions
00243 ("sbs-right-dimensions", "0.5 1.0 0.0 1.0",
00244  PRC_DESC("Defines the default region of the window that is used for the "
00245           "right eye, when side-by-side stereo is enabled.  This is a set of "
00246           "four numbers, in the form left right top bottom, similar to a "
00247           "normal DisplayRegion layout."));
00248 
00249 ConfigVariableBool swap_eyes
00250 ("swap-eyes", false,
00251  PRC_DESC("Set this true to reverse the left and right channel output of "
00252           "stereo DisplayRegions."));
00253 
00254 ConfigVariableBool default_stereo_camera
00255 ("default-stereo-camera", true,
00256  PRC_DESC("When this is true, the default DisplayRegion created for "
00257           "a window or buffer with the stereo property will be a "
00258           "StereoDisplayRegion, which activates the stereo properties of "
00259           "the camera lens, and enables stereo.  Set this false to "
00260           "require StereoDisplayRegions to be created explicitly."));
00261 
00262 ConfigVariableBool color_scale_via_lighting
00263 ("color-scale-via-lighting", true,
00264  PRC_DESC("When this is true, Panda will try to implement ColorAttribs and "
00265           "ColorScaleAttribs using the lighting interface, by "
00266           "creating a default material and/or an ambient light if "
00267           "necessary, even if lighting is ostensibly disabled.  This "
00268           "avoids the need to munge the vertex data to change each vertex's "
00269           "color.  Set this false to avoid this trickery, so that lighting "
00270           "is only enabled when the application specifically enables "
00271           "it.  See also alpha-scale-via-texture."));
00272 
00273 ConfigVariableBool alpha_scale_via_texture
00274 ("alpha-scale-via-texture", true,
00275  PRC_DESC("When this is true, Panda will try to implement "
00276           "ColorScaleAttribs that affect alpha by "
00277           "creating an additional Texture layer over the geometry "
00278           "with a uniform alpha scale applied everywhere, if there "
00279           "is at least one available Texture slot available on the "
00280           "multitexture pipeline.  Set this false to avoid this "
00281           "trickery, so that texturing is only enabled when the "
00282           "application specifically enables it.  See also "
00283           "color-scale-via-lighting."));
00284 
00285 ConfigVariableBool allow_incomplete_render
00286 ("allow-incomplete-render", true,
00287  PRC_DESC("When this is true, the frame may be rendered even if some of the "
00288           "geometry in the scene has been paged out, or if the textures are "
00289           "unavailable.  The nonresident geometry and textures will be "
00290           "rendered as soon as they can be read from disk, "
00291           "which may be several frames in the future.  When this is false, "
00292           "geometry is always paged in immediately when needed, holding up "
00293           "the frame render if necessary."));
00294 
00295 ConfigVariableInt win_size
00296 ("win-size", "640 480",
00297  PRC_DESC("This is the default size at which to open a new window.  This "
00298           "replaces the deprecated win-width and win-height variables."));
00299 
00300 ConfigVariableInt win_origin
00301 ("win-origin", "",
00302  PRC_DESC("This is the default position at which to open a new window.  This "
00303           "replaces the deprecated win-origin-x and win-origin-y variables. "
00304           "A window coordinate of -1 means to choose a default value, "
00305           "whereas -2 means to center the window on the screen."));
00306 
00307 ConfigVariableBool fullscreen
00308 ("fullscreen", false);
00309 
00310 ConfigVariableBool undecorated
00311 ("undecorated", false,
00312  PRC_DESC("This specifies the default value of the 'undecorated' window "
00313           "property.  When this is true, the default window is created "
00314           "without a title bar or resizable border."));
00315 
00316 ConfigVariableBool win_fixed_size
00317 ("win-fixed-size", false,
00318  PRC_DESC("This specifies the default value of the 'fixed_size' window "
00319           "property.  When this is true, the default window is created "
00320           "without a resizable border."));
00321 
00322 ConfigVariableBool cursor_hidden
00323 ("cursor-hidden", false);
00324 
00325 ConfigVariableFilename icon_filename
00326 ("icon-filename", "");
00327 
00328 ConfigVariableFilename cursor_filename
00329 ("cursor-filename", "");
00330 
00331 ConfigVariableEnum<WindowProperties::ZOrder> z_order
00332 ("z-order", WindowProperties::Z_normal);
00333 
00334 ConfigVariableString window_title
00335 ("window-title", "Panda");
00336 
00337 ConfigVariableInt parent_window_handle
00338 ("parent-window-handle", 0,
00339  PRC_DESC("The window handle of the parent window to attach the Panda window "
00340           "to, for the purposes of creating an embedded window.  This is "
00341           "an HWND on Windows, or the NSWindow pointer or XWindow pointer "
00342           "converted to an integer, on OSX and X11."));
00343 
00344 ConfigVariableBool win_unexposed_draw
00345 ("win-unexposed-draw", true,
00346  PRC_DESC("Specifies the default setting of GraphicsWindow::set_unexposed_draw().  "
00347           "See that method for more information."));
00348 
00349 ConfigVariableFilename subprocess_window
00350 ("subprocess-window", "",
00351  PRC_DESC("The filename of a SubprocessWindowBuffer's temporary mmap file, "
00352           "used for opening a window in a child process and rendering "
00353           "to a different window in the parent process.  "
00354           "This is specifically used for OSX when the plugin is compiled, "
00355           "and is not used or needed in other environments.  See "
00356           "WindowProperties::set_subprocess_window()."));
00357 
00358 ConfigVariableString framebuffer_mode
00359 ("framebuffer-mode", "",
00360  PRC_DESC("No longer has any effect.  Do not use."));
00361 
00362 ConfigVariableBool framebuffer_hardware
00363 ("framebuffer-hardware", true,
00364  PRC_DESC("True if FM_hardware should be added to the default framebuffer "
00365           "properties, which requests a hardware-accelerated display."));
00366 ConfigVariableBool framebuffer_software
00367 ("framebuffer-software", false,
00368  PRC_DESC("True if FM_software should be added to the default framebuffer "
00369           "properties, which requests a software-only display."));
00370 ConfigVariableBool framebuffer_multisample
00371 ("framebuffer-multisample", false,
00372  PRC_DESC("True if FM_multisample should be added to the default framebuffer "
00373           "properties, which requests a multisample-capable display, if "
00374           "possible.  This can be used to implement full-screen "
00375           "antialiasing."));
00376 ConfigVariableBool framebuffer_depth
00377 ("framebuffer-depth", true,
00378  PRC_DESC("True if FM_depth should be added to the default framebuffer "
00379           "properties, which requests a depth buffer."));
00380 ConfigVariableBool framebuffer_alpha
00381 ("framebuffer-alpha", true,
00382  PRC_DESC("True if FM_alpha should be added to the default framebuffer "
00383           "properties, which requests an alpha channel if possible."));
00384 ConfigVariableBool framebuffer_stencil
00385 ("framebuffer-stencil", false,
00386  PRC_DESC("True if FM_stencil should be added to the default framebuffer "
00387           "properties, which requests an stencil buffer if possible."));
00388 ConfigVariableBool framebuffer_accum
00389 ("framebuffer-accum", false,
00390  PRC_DESC("True if FM_accum should be added to the default framebuffer "
00391           "properties, which requests an accumulator buffer if possible."));
00392 ConfigVariableBool framebuffer_stereo
00393 ("framebuffer-stereo", false,
00394  PRC_DESC("True if FM_stereo should be added to the default framebuffer "
00395           "properties, which requests a stereo-capable display, if "
00396           "supported by the graphics driver."));
00397 
00398 ConfigVariableInt depth_bits
00399 ("depth-bits", 0,
00400  PRC_DESC("The minimum number of depth buffer bits requested."));
00401 ConfigVariableInt color_bits
00402 ("color-bits", 0,
00403  PRC_DESC("The minimum number of color buffer bits requested."));
00404 ConfigVariableInt alpha_bits
00405 ("alpha-bits", 0,
00406  PRC_DESC("The minimum number of alpha buffer bits requested."));
00407 ConfigVariableInt stencil_bits
00408 ("stencil-bits", 0,
00409  PRC_DESC("The minimum number of stencil buffer bits requested."));
00410 ConfigVariableInt accum_bits
00411 ("accum-bits", 0,
00412  PRC_DESC("The minimum number of accumulator buffer bits requested."));
00413 ConfigVariableInt multisamples
00414 ("multisamples", 0,
00415  PRC_DESC("The minimum number of samples requested."));
00416 ConfigVariableInt back_buffers
00417 ("back-buffers", 1,
00418  PRC_DESC("The default number of back buffers requested."));
00419 
00420 ConfigVariableDouble pixel_zoom
00421 ("pixel-zoom", 1.0,
00422  PRC_DESC("The default pixel_zoom factor for new windows."));
00423 
00424 ConfigVariableDouble background_color
00425 ("background-color", "0.41 0.41 0.41",
00426  PRC_DESC("Specifies the rgb(a) value of the default background color for a "
00427           "new window or offscreen buffer."));
00428 
00429 ConfigVariableBool sync_video
00430 ("sync-video", true,
00431  PRC_DESC("Configure this true to request the rendering to sync to the video "
00432           "refresh, or false to let your frame rate go as high as it can, "
00433           "irrespective of the video refresh.  Usually you want this true, "
00434           "but it may be useful to set it false during development for a "
00435           "cheesy estimate of scene complexity.  Some drivers may ignore "
00436           "this request."));
00437 
00438 ConfigVariableBool basic_shaders_only
00439 ("basic-shaders-only", false,
00440  PRC_DESC("Set this to true if you aren't interested in shader model three "
00441           "and beyond.  Setting this flag will cause panda to disable "
00442           "bleeding-edge shader functionality which tends to be unreliable "
00443           "or broken.  At some point, when functionality that is currently "
00444           "flaky becomes reliable, we may expand the definition of what "
00445           "constitutes 'basic' shaders."));
00446 
00447 ////////////////////////////////////////////////////////////////////
00448 //     Function: init_libdisplay
00449 //  Description: Initializes the library.  This must be called at
00450 //               least once before any of the functions or classes in
00451 //               this library can be used.  Normally it will be
00452 //               called by the static initializers and need not be
00453 //               called explicitly, but special cases exist.
00454 ////////////////////////////////////////////////////////////////////
00455 void
00456 init_libdisplay() {
00457   static bool initialized = false;
00458   if (initialized) {
00459     return;
00460   }
00461   initialized = true;
00462 
00463   CallbackGraphicsWindow::init_type();
00464   DisplayRegion::init_type();
00465   DisplayRegionCullCallbackData::init_type();
00466   DisplayRegionDrawCallbackData::init_type();
00467   DisplayRegionPipelineReader::init_type();
00468   GraphicsBuffer::init_type();
00469   GraphicsDevice::init_type();
00470   GraphicsOutput::init_type();
00471   GraphicsPipe::init_type();
00472   GraphicsStateGuardian::init_type();
00473   GraphicsWindow::init_type();
00474 #ifdef HAVE_PYTHON
00475   PythonGraphicsWindowProc::init_type();
00476 #endif
00477   GraphicsWindowProcCallbackData::init_type();
00478   NativeWindowHandle::init_type();
00479   ParasiteBuffer::init_type();
00480   StandardMunger::init_type();
00481   StereoDisplayRegion::init_type();
00482 #ifdef SUPPORT_SUBPROCESS_WINDOW
00483   SubprocessWindow::init_type();
00484 #endif
00485   WindowHandle::init_type();
00486   WindowHandle::OSHandle::init_type();
00487 
00488 #if defined(HAVE_THREADS) && defined(DO_PIPELINING)
00489   PandaSystem *ps = PandaSystem::get_global_ptr();
00490   ps->add_system("pipelining");
00491 #endif
00492 }
 All Classes Functions Variables Enumerations