diff options
Diffstat (limited to 'doc/python_api/rst/bge.texture.rst')
| -rw-r--r-- | doc/python_api/rst/bge.texture.rst | 119 |
1 files changed, 98 insertions, 21 deletions
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 |