diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/python_api/rst/bge.logic.rst | 22 | ||||
| -rw-r--r-- | doc/python_api/rst/bge.render.rst | 61 | ||||
| -rw-r--r-- | doc/python_api/rst/bge.texture.rst | 119 |
3 files changed, 181 insertions, 21 deletions
diff --git a/doc/python_api/rst/bge.logic.rst b/doc/python_api/rst/bge.logic.rst index 3f35901234a..5cdb8ebfee9 100644 --- a/doc/python_api/rst/bge.logic.rst +++ b/doc/python_api/rst/bge.logic.rst @@ -378,6 +378,28 @@ General functions Render next frame (if Python has control) +.. function:: setRender(render) + + Sets the global flag that controls the render of the scene. + If True, the render is done after the logic frame. + If False, the render is skipped and another logic frame starts immediately. + + .. note:: + + GPU VSync no longer limits the number of frame per second when render is off, + but the *Use Frame Rate* option still regulates the fps. To run as many frames + as possible, untick this option (Render Properties, System panel). + + :arg render: the render flag + :type render: bool + +.. function:: getRender() + + Get the current value of the global render flag + + :return: The flag value + :rtype: bool + ********************** Time related functions ********************** diff --git a/doc/python_api/rst/bge.render.rst b/doc/python_api/rst/bge.render.rst index 3b565e294dd..02c3beef672 100644 --- a/doc/python_api/rst/bge.render.rst +++ b/doc/python_api/rst/bge.render.rst @@ -90,6 +90,48 @@ Constants Right eye being used during stereoscopic rendering. +.. data:: RAS_OFS_RENDER_BUFFER + + The pixel buffer for offscreen render is a RenderBuffer. Argument to :func:`offScreenCreate` + +.. data:: RAS_OFS_RENDER_TEXTURE + + The pixel buffer for offscreen render is a Texture. Argument to :func:`offScreenCreate` + + +***** +Types +***** + +.. class:: RASOffScreen + + An off-screen render buffer object. + + Use :func:`offScreenCreate` to create it. + Currently it can only be used in the :class:`bge.texture.ImageRender` + constructor to render on a FBO rather than the default viewport. + + .. attribute:: width + + The width in pixel of the FBO + + :type: integer + + .. attribute:: height + + The height in pixel of the FBO + + :type: integer + + .. attribute:: color + + The underlying OpenGL bind code of the texture object that holds + the rendered image, 0 if the FBO is using RenderBuffer. + The choice between RenderBuffer and Texture is determined + by the target argument of :func:`offScreenCreate`. + + :type: integer + ********* Functions @@ -362,3 +404,22 @@ Functions Get the current vsync value :rtype: One of VSYNC_OFF, VSYNC_ON, VSYNC_ADAPTIVE + +.. function:: offScreenCreate(width,height[,samples=0][,target=bge.render.RAS_OFS_RENDER_BUFFER]) + + Create a Off-screen render buffer object. + + :arg width: the width of the buffer in pixels + :type width: integer + :arg height: the height of the buffer in pixels + :type height: integer + :arg samples: the number of multisample for anti-aliasing (MSAA), 0 to disable MSAA + :type samples: integer + :arg target: the pixel storage: :data:`RAS_OFS_RENDER_BUFFER` to render on RenderBuffers (the default), + :data:`RAS_OFS_RENDER_TEXTURE` to render on texture. + The later is interesting if you want to access the texture directly (see :attr:`RASOffScreen.color`). + Otherwise the default is preferable as it's more widely supported by GPUs and more efficient. + If the GPU does not support MSAA+Texture (e.g. Intel HD GPU), MSAA will be disabled. + :type target: integer + :rtype: :class:`RASOffScreen` + diff --git a/doc/python_api/rst/bge.texture.rst b/doc/python_api/rst/bge.texture.rst index 4588a3e1800..e226d2f90c0 100644 --- a/doc/python_api/rst/bge.texture.rst +++ b/doc/python_api/rst/bge.texture.rst @@ -173,14 +173,23 @@ Video classes :return: Whether the video was playing. :rtype: bool - .. method:: refresh() - - Refresh video - get its status. - - :value: see `FFmpeg Video and Image Status`_. - + .. method:: refresh(buffer=None, format="RGBA", timestamp=-1.0) + + Refresh video - get its status and optionally copy the frame to an external buffer. + + :arg buffer: An optional object that implements the buffer protocol. + If specified, the image is copied to the buffer, which must be big enough or an exception is thrown. + :type buffer: any buffer type + :arg format: An optional image format specifier for the image that will be copied to the buffer. + Only valid values are "RGBA" or "BGRA" + :type format: str + :arg timestamp: An optional timestamp (in seconds from the start of the movie) + of the frame to be copied to the buffer. + :type timestamp: float + :return: see `FFmpeg Video and Image Status`_. :rtype: int + ************* Image classes ************* @@ -244,12 +253,17 @@ Image classes * :class:`FilterRGB24` * :class:`FilterRGBA32` - .. method:: refresh() + .. method:: refresh(buffer=None, format="RGBA") - Refresh image, i.e. load it. + Refresh image, get its status and optionally copy the frame to an external buffer. - :value: see `FFmpeg Video and Image Status`_. - + :arg buffer: An optional object that implements the buffer protocol. + If specified, the image is copied to the buffer, which must be big enough or an exception is thrown. + :type buffer: any buffer type + :arg format: An optional image format specifier for the image that will be copied to the buffer. + Only valid values are "RGBA" or "BGRA" + :type format: str + :return: see `FFmpeg Video and Image Status`_. :rtype: int .. method:: reload(newname=None) @@ -411,9 +425,18 @@ Image classes :type: :class:`~bgl.Buffer` or None - .. method:: refresh() + .. method:: refresh(buffer=None, format="RGBA") - Refresh image - invalidate its current content. + Refresh image - render and copy the image to an external buffer (optional) + then invalidate its current content. + + :arg buffer: An optional object that implements the buffer protocol. + If specified, the image is rendered and copied to the buffer, + which must be big enough or an exception is thrown. + :type buffer: any buffer type + :arg format: An optional image format specifier for the image that will be copied to the buffer. + Only valid values are "RGBA" or "BGRA" + :type format: str .. attribute:: scale @@ -498,9 +521,17 @@ Image classes :type: :class:`~bgl.Buffer` or None - .. method:: refresh() + .. method:: refresh(buffer=None, format="RGBA") + + Refresh image - calculate and copy the image to an external buffer (optional) then invalidate its current content. - Refresh image - invalidate its current content. + :arg buffer: An optional object that implements the buffer protocol. + If specified, the image is calculated and copied to the buffer, + which must be big enough or an exception is thrown. + :type buffer: any buffer type + :arg format: An optional image format specifier for the image that will be copied to the buffer. + Only valid values are "RGBA" or "BGRA" + :type format: str .. attribute:: scale @@ -545,14 +576,18 @@ Image classes :type: bool -.. class:: ImageRender(scene, camera) +.. class:: ImageRender(scene, camera, fbo=None) Image source from render. + The render is done on a custom framebuffer object if fbo is specified, + otherwise on the default framebuffer. :arg scene: Scene in which the image has to be taken. :type scene: :class:`~bge.types.KX_Scene` :arg camera: Camera from which the image has to be taken. :type camera: :class:`~bge.types.KX_Camera` + :arg fbo: Off-screen render buffer object (optional) + :type fbo: :class:`~bge.render.RASOffScreen` .. attribute:: alpha @@ -599,10 +634,6 @@ Image classes :type: :class:`~bgl.Buffer` or None - .. method:: refresh() - - Refresh image - invalidate its current content. - .. attribute:: scale Fast scale of image (near neighbour). @@ -640,6 +671,42 @@ Image classes :type: bool + .. method:: render() + + Render the scene but do not extract the pixels yet. + The function returns as soon as the render commands have been send to the GPU. + The render will proceed asynchronously in the GPU while the host can perform other tasks. + To complete the render, you can either call :func:`refresh` + directly of refresh the texture of which this object is the source. + This method is useful to implement asynchronous render for optimal performance: call render() + on frame n and refresh() on frame n+1 to give as much as time as possible to the GPU + to render the frame while the game engine can perform other tasks. + + :return: True if the render was initiated, False if the render cannot be performed (e.g. the camera is active) + :rtype: bool + + .. method:: refresh() + .. method:: refresh(buffer, format="RGBA") + + Refresh video - render and optionally copy the image to an external buffer then invalidate its current content. + The render may have been started earlier with the :func:`render` method, + in which case this function simply waits for the render operations to complete. + When called without argument, the pixels are not extracted but the render is guaranteed + to be completed when the function returns. + This only makes sense with offscreen render on texture target (see :func:`~bge.render.offScreenCreate`). + + :arg buffer: An object that implements the buffer protocol. + If specified, the image is copied to the buffer, which must be big enough or an exception is thrown. + The transfer to the buffer is optimal if no processing of the image is needed. + This is the case if ``flip=False, alpha=True, scale=False, whole=True, depth=False, zbuff=False`` + and no filter is set. + :type buffer: any buffer type of sufficient size + :arg format: An optional image format specifier for the image that will be copied to the buffer. + Only valid values are "RGBA" or "BGRA" + :type format: str + :return: True if the render is complete, False if the render cannot be performed (e.g. the camera is active) + :rtype: bool + .. class:: ImageViewport Image source from viewport. @@ -689,9 +756,19 @@ Image classes :type: sequence of two ints - .. method:: refresh() + .. method:: refresh(buffer=None, format="RGBA") + + Refresh video - copy the viewport to an external buffer (optional) then invalidate its current content. - Refresh image - invalidate its current content. + :arg buffer: An optional object that implements the buffer protocol. + If specified, the image is copied to the buffer, which must be big enough or an exception is thrown. + The transfer to the buffer is optimal if no processing of the image is needed. + This is the case if ``flip=False, alpha=True, scale=False, whole=True, depth=False, zbuff=False`` + and no filter is set. + :type buffer: any buffer type + :arg format: An optional image format specifier for the image that will be copied to the buffer. + Only valid values are "RGBA" or "BGRA" + :type format: str .. attribute:: scale |