diff options
Diffstat (limited to 'doc/python_api/rst/bge.render.rst')
| -rw-r--r-- | doc/python_api/rst/bge.render.rst | 164 |
1 files changed, 85 insertions, 79 deletions
diff --git a/doc/python_api/rst/bge.render.rst b/doc/python_api/rst/bge.render.rst index 9dd4057c82f..2afb2796249 100644 --- a/doc/python_api/rst/bge.render.rst +++ b/doc/python_api/rst/bge.render.rst @@ -8,9 +8,14 @@ Intro .. module:: bge.render +Example of using a :class:`bge.types.SCA_MouseSensor`, +and two :class:`bge.types.KX_ObjectActuator` to implement MouseLook: + +.. note:: + This can also be achieved with the :class:`bge.types.KX_MouseActuator`. + .. code-block:: python - # Example Uses an L{SCA_MouseSensor}, and two L{KX_ObjectActuator}s to implement MouseLook:: # To use a mouse movement sensor "Mouse" and a # motion actuator to mouse look: import bge @@ -62,7 +67,7 @@ Constants .. data:: KX_BLENDER_GLSL_MATERIAL Materials approximating blender materials with GLSL. - + .. DATA:: VSYNC_OFF Disables vsync @@ -73,7 +78,18 @@ Constants .. DATA:: VSYNC_ADAPTIVE - Enables adaptive vsync if supported. Adaptive vsync enables vsync if the framerate is above the monitors refresh rate. Otherwise, vsync is diabled if the framerate is too low. + Enables adaptive vsync if supported. + Adaptive vsync enables vsync if the framerate is above the monitors refresh rate. + Otherwise, vsync is diabled if the framerate is too low. + +.. data:: LEFT_EYE + + Left eye being used during stereoscopic rendering. + +.. data:: RIGHT_EYE + + Right eye being used during stereoscopic rendering. + ********* Functions @@ -82,47 +98,64 @@ Functions .. function:: getWindowWidth() Gets the width of the window (in pixels) - + :rtype: integer .. function:: getWindowHeight() Gets the height of the window (in pixels) - + :rtype: integer .. function:: setWindowSize(width, height) Set the width and height of the window (in pixels). This also works for fullscreen applications. - + + .. note:: Only works in the standalone player, not the Blender-embedded player. + :type width: integer :type height: integer .. function:: setFullScreen(enable) Set whether or not the window should be fullscreen. - + + .. note:: Only works in the standalone player, not the Blender-embedded player. + :type enable: bool .. function:: getFullScreen() Returns whether or not the window is fullscreen. - + + .. note:: Only works in the standalone player, not the Blender-embedded player; there it always returns False. + :rtype: bool -.. function:: makeScreenshot(filename) +.. function:: getDisplayDimensions() - Writes a screenshot to the given filename. - - If filename starts with // the image will be saved relative to the current directory. - If the filename contains # it will be replaced with the frame number. - - The standalone player saves .png files. It does not support color space conversion - or gamma correction. - - When run from Blender, makeScreenshot supports all Blender image file formats like PNG, TGA, Jpeg and OpenEXR. - Gamma, Colorspace conversion and Jpeg compression are taken from the Render settings panels. + Get the actual display dimensions, in pixels, of the physical display (e.g., the monitor). + :type dimension: list [width,heigh] + +.. function:: makeScreenshot(filename) + + Writes an image file with the current displayed frame. + + The image is written to *'filename'*. + The path may be absolute (eg. ``/home/foo/image``) or relative when started with + ``//`` (eg. ``//image``). Note that absolute paths are not portable between platforms. + If the filename contains a ``#``, + it will be replaced by an incremental index so that screenshots can be taken multiple + times without overwriting the previous ones (eg. ``image-#``). + + Settings for the image are taken from the render settings (file format and respective settings, + gamma and colospace conversion, etc). + The image resolution matches the framebuffer, meaning, the window size and aspect ratio. + When running from the standalone player, instead of the embedded player, only PNG files are supported. + Additional color conversions are also not supported. + + :arg filename: path and name of the file to write :type filename: string @@ -134,65 +167,29 @@ Functions .. function:: showMouse(visible) Enables or disables the operating system mouse cursor. - + :type visible: boolean .. function:: setMousePosition(x, y) Sets the mouse cursor position. - + :type x: integer :type y: integer .. function:: setBackgroundColor(rgba) - Sets the window background color. - - :type rgba: list [r, g, b, a] - - -.. function:: setMistColor(rgb) - - Sets the mist color. - - :type rgb: list [r, g, b] - - -.. function:: setAmbientColor(rgb) - - Sets the color of ambient light. - - :type rgb: list [r, g, b] - - -.. function:: setMistStart(start) - - Sets the mist start value. Objects further away than start will have mist applied to them. - - :type start: float + Sets the window background color. (Deprecated: use KX_WorldInfo.background_color) + :type rgba: list [r, g, b, a] -.. function:: setMistEnd(end) - - Sets the mist end value. Objects further away from this will be colored solid with - the color set by setMistColor(). - - :type end: float - - -.. function:: disableMist() - - Disables mist. - - .. note:: Set any of the mist properties to enable mist. - .. function:: setEyeSeparation(eyesep) Sets the eye separation for stereo mode. Usually Focal Length/30 provides a confortable value. - + :arg eyesep: The distance between the left and right eye. :type eyesep: float @@ -200,27 +197,36 @@ Functions .. function:: getEyeSeparation() Gets the current eye separation for stereo mode. - + :rtype: float - + .. function:: setFocalLength(focallength) Sets the focal length for stereo mode. It uses the current camera focal length as initial value. - - :arg focallength: The focal length. + + :arg focallength: The focal length. :type focallength: float .. function:: getFocalLength() Gets the current focal length for stereo mode. - + :rtype: float +.. function:: getStereoEye() + + Gets the current stereoscopy eye being rendered. + This function is mainly used in a :class:`bge.types.KX_Scene.pre_draw` callback + function to customize the camera projection matrices for each + stereoscopic eye. + + :rtype: LEFT_EYE, RIGHT_EYE + .. function:: setMaterialMode(mode) Set the material mode to use for OpenGL rendering. - + :type mode: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL .. note:: Changes will only affect newly created scenes. @@ -229,14 +235,14 @@ Functions .. function:: getMaterialMode(mode) Get the material mode to use for OpenGL rendering. - + :rtype: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL .. function:: setGLSLMaterialSetting(setting, enable) Enables or disables a GLSL material setting. - + :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures) :type enable: boolean @@ -244,43 +250,43 @@ Functions .. function:: getGLSLMaterialSetting(setting, enable) Get the state of a GLSL material setting. - + :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures) :rtype: boolean .. function:: setAnisotropicFiltering(level) Set the anisotropic filtering level for textures. - + :arg level: The new anisotropic filtering level to use :type level: integer (must be one of 1, 2, 4, 8, 16) - + .. note:: Changing this value can cause all textures to be recreated, which can be slow. - + .. function:: getAnisotropicFiltering() Get the anisotropic filtering level used for textures. - + :rtype: integer (one of 1, 2, 4, 8, 16) .. function:: setMipmapping(value) Change how to use mipmapping. - + :type value: RAS_MIPMAP_NONE, RAS_MIPMAP_NEAREST, RAS_MIPMAP_LINEAR - + .. note:: Changing this value can cause all textures to be recreated, which can be slow. .. function:: getMipmapping() Get the current mipmapping setting. - + :rtype: RAS_MIPMAP_NONE, RAS_MIPMAP_NEAREST, RAS_MIPMAP_LINEAR - + .. function:: drawLine(fromVec,toVec,color) Draw a line in the 3D scene. - + :arg fromVec: the origin of the line :type fromVec: list [x, y, z] :arg toVec: the end of the line @@ -292,7 +298,7 @@ Functions .. function:: enableMotionBlur(factor) Enable the motion blur effect. - + :arg factor: the ammount of motion blur to display. :type factor: float [0.0 - 1.0] |