Updating python API documentation for function bge.render.makeScreenshot

1 files changed, 41 insertions, 39 deletions

diff --git a/doc/python_api/rst/bge.render.rst b/doc/python_api/rst/bge.render.rst
index d185a5d05aa..651693b7a8a 100644
--- a/doc/python_api/rst/bge.render.rst
+++ b/doc/python_api/rst/bge.render.rst
@@ -66,7 +66,7 @@ Constants
 .. data:: KX_BLENDER_GLSL_MATERIAL
 
    Materials approximating blender materials with GLSL.
-   
+
 .. DATA:: VSYNC_OFF
 
    Disables vsync
@@ -95,47 +95,49 @@ 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.
-   
+
    :type width: integer
    :type height: integer
 
 .. function:: setFullScreen(enable)
 
    Set whether or not the window should be fullscreen.
-   
+
    :type enable: bool
 
 .. function:: getFullScreen()
 
    Returns whether or not the window is fullscreen.
-   
+
    :rtype: bool
 
 .. function:: makeScreenshot(filename)
 
-   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.
-   
+   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
 
 
@@ -147,14 +149,14 @@ 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
 
@@ -169,7 +171,7 @@ Functions
 .. 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
 
@@ -177,21 +179,21 @@ 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()
@@ -206,7 +208,7 @@ Functions
 .. 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.
@@ -215,14 +217,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
 
@@ -230,43 +232,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
@@ -278,7 +280,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]