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