forked from bartvdbraak/blender
patch [#27871] bge.texture documentation from Solano Felício (+ changes from me) it still needs work
... and I can't test rst in windows so for now let's pretend it builds. If someone can generate the docs and see how it goes please let me know. (plus a small fix for bge.logic rst)
This commit is contained in:
Dalai Felinto
parent
e7878389bb
commit
26d75618ef
@ -17,7 +17,7 @@ Module to access logic functions, imported automatically into the python control
|
||||
# To get the game object this controller is on:
|
||||
obj = cont.owner
|
||||
|
||||
:class:`~bge.types.KX_GameObject` and :class:`~bge.types.KX_Camera` or :class:`bge.types.~KX_LightObject` methods are available depending on the type of object
|
||||
:class:`~bge.types.KX_GameObject` and :class:`~bge.types.KX_Camera` or :class:`~bge.types.KX_LightObject` methods are available depending on the type of object
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
|
||||
480
doc/python_api/rst/bge.texture.rst
Normal file
480
doc/python_api/rst/bge.texture.rst
Normal file
@ -0,0 +1,480 @@
|
||||
|
||||
Game Engine bge.texture Module
|
||||
==============================
|
||||
.. note::
|
||||
This documentation is still very weak, and needs some help! Right now they are mostly a collection
|
||||
of the docstrings found in the bge.texture source code + some random places filled with text.
|
||||
|
||||
*****
|
||||
Intro
|
||||
*****
|
||||
|
||||
The bge.texture module allows you to manipulate textures during the game.
|
||||
|
||||
Several sources for texture are possible: video files, image files, video capture, memory buffer, camera render or a mix of that.
|
||||
|
||||
The video and image files can be loaded from the internet using an URL instead of a file name.
|
||||
|
||||
In addition, you can apply filters on the images before sending them to the GPU, allowing video effect: blue screen, color band, gray, normal map.
|
||||
|
||||
bge.texture uses FFmpeg to load images and videos. All the formats and codecs that FFmpeg supports are supported by this module, including but not limited to::
|
||||
|
||||
* AVI
|
||||
* Ogg
|
||||
* Xvid
|
||||
* Theora
|
||||
* dv1394 camera
|
||||
* video4linux capture card (this includes many webcams)
|
||||
* videoForWindows capture card (this includes many webcams)
|
||||
* JPG
|
||||
|
||||
The principle is simple: first you identify a texture on an existing object using
|
||||
the :materialID: function, then you create a new texture with dynamic content
|
||||
and swap the two textures in the GPU.
|
||||
|
||||
The GE is not aware of the substitution and continues to display the object as always,
|
||||
except that you are now in control of the texture.
|
||||
|
||||
When the texture object is deleted, the new texture is deleted and the old texture restored.
|
||||
|
||||
.. module:: bge.texture
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import bge
|
||||
from bge import texture
|
||||
from bge import logic
|
||||
|
||||
cont = logic.getCurrentController()
|
||||
obj = cont.owner
|
||||
|
||||
# the creation of the texture must be done once: save the
|
||||
# texture object in an attribute of GameLogic module makes it persistent
|
||||
if not hasattr(logic, 'video'):
|
||||
|
||||
# identify a static texture by name
|
||||
matID = texture.materialID(obj, 'IMvideo.png')
|
||||
|
||||
# create a dynamic texture that will replace the static texture
|
||||
logic.video = texture.Texture(obj, matID)
|
||||
|
||||
# define a source of image for the texture, here a movie
|
||||
movie = logic.expandPath('//trailer_400p.ogg')
|
||||
logic.video.source = texture.VideoFFmpeg(movie)
|
||||
logic.video.source.scale = True
|
||||
|
||||
# quick off the movie, but it wont play in the background
|
||||
logic.video.source.play()
|
||||
|
||||
# you need to call this function every frame to ensure update of the texture.
|
||||
logic.video.refresh(True)
|
||||
|
||||
.. class:: VideoFFmpeg(file [, capture=-1, rate=25.0, width=0, height=0])
|
||||
|
||||
FFmpeg video source
|
||||
|
||||
.. attribute:: status
|
||||
video status
|
||||
|
||||
.. attribute:: range
|
||||
replay range
|
||||
|
||||
.. attribute:: repeat
|
||||
repeat count, -1 for infinite repeat
|
||||
|
||||
:type: int
|
||||
|
||||
.. attribute:: framerate
|
||||
frame rate
|
||||
|
||||
:type: float
|
||||
|
||||
.. attribute:: valid
|
||||
Tells if an image is available
|
||||
|
||||
:type: bool
|
||||
|
||||
.. attribute:: image
|
||||
image data
|
||||
|
||||
.. attribute:: size
|
||||
image size
|
||||
|
||||
.. attribute:: scale
|
||||
fast scale of image (near neighbour)
|
||||
|
||||
.. attribute:: flip
|
||||
flip image vertically
|
||||
|
||||
.. attribute:: filter
|
||||
pixel filter
|
||||
|
||||
.. attribute:: preseek
|
||||
number of frames of preseek
|
||||
|
||||
:type: int
|
||||
|
||||
.. attribute:: deinterlace
|
||||
deinterlace image
|
||||
|
||||
:type: bool
|
||||
|
||||
.. method:: play()
|
||||
Play (restart) video
|
||||
|
||||
.. method:: pause()
|
||||
pause video
|
||||
|
||||
.. method:: stop()
|
||||
stop video (play will replay it from start)
|
||||
|
||||
.. method:: refresh()
|
||||
Refresh video - get its status
|
||||
|
||||
.. class:: ImageFFmpeg(file)
|
||||
|
||||
FFmpeg image source
|
||||
|
||||
.. attribute:: status
|
||||
video status
|
||||
|
||||
.. attribute:: valid
|
||||
Tells if an image is available
|
||||
|
||||
:type: bool
|
||||
|
||||
.. attribute:: image
|
||||
image data
|
||||
|
||||
.. attribute:: size
|
||||
image size
|
||||
|
||||
.. attribute:: scale
|
||||
fast scale of image (near neighbour)
|
||||
|
||||
.. attribute:: flip
|
||||
flip image vertically
|
||||
|
||||
.. attribute:: filter
|
||||
pixel filter
|
||||
|
||||
.. method:: refresh()
|
||||
Refresh image, i.e. load it
|
||||
|
||||
.. method:: reload([newname])
|
||||
Reload image, i.e. reopen it
|
||||
|
||||
.. class:: ImageBuff()
|
||||
|
||||
Image source from image buffer
|
||||
|
||||
.. attribute:: filter
|
||||
pixel filter
|
||||
|
||||
.. attribute:: flip
|
||||
flip image vertically
|
||||
|
||||
.. attribute:: image
|
||||
image data
|
||||
|
||||
.. method:: load(imageBuffer, width, height)
|
||||
Load image from buffer
|
||||
|
||||
.. method:: plot(imageBuffer, width, height, positionX, positionY)
|
||||
update image buffer
|
||||
|
||||
.. attribute:: scale
|
||||
fast scale of image (near neighbour)
|
||||
|
||||
.. attribute:: size
|
||||
image size
|
||||
|
||||
.. attribute:: valid
|
||||
bool to tell if an image is available
|
||||
|
||||
.. class:: ImageMirror(scene)
|
||||
|
||||
Image source from mirror
|
||||
|
||||
.. attribute:: alpha
|
||||
use alpha in texture
|
||||
|
||||
.. attribute:: background
|
||||
background color
|
||||
|
||||
.. attribute:: capsize
|
||||
size of render area
|
||||
|
||||
.. attribute:: clip
|
||||
clipping distance
|
||||
|
||||
.. attribute:: filter
|
||||
pixel filter
|
||||
|
||||
.. attribute:: flip
|
||||
flip image vertically
|
||||
|
||||
.. attribute:: image
|
||||
image data
|
||||
|
||||
.. method:: refresh(imageMirror)
|
||||
Refresh image - invalidate its current content
|
||||
|
||||
.. attribute:: scale
|
||||
fast scale of image (near neighbour)
|
||||
|
||||
.. attribute:: size
|
||||
image size
|
||||
|
||||
.. attribute:: valid
|
||||
bool to tell if an image is available
|
||||
|
||||
.. attribute:: whole
|
||||
use whole viewport to render
|
||||
|
||||
.. class:: ImageMix()
|
||||
|
||||
Image mixer
|
||||
|
||||
.. attribute:: filter
|
||||
pixel filter
|
||||
|
||||
.. attribute:: flip
|
||||
flip image vertically
|
||||
|
||||
.. method:: getSource(imageMix)
|
||||
get image source
|
||||
|
||||
.. method:: getWeight(imageMix)
|
||||
get image source weight
|
||||
|
||||
.. attribute:: image
|
||||
image data
|
||||
|
||||
.. method:: refresh(imageMix)
|
||||
Refresh image - invalidate its current content
|
||||
|
||||
.. attribute:: scale
|
||||
fast scale of image (near neighbour)
|
||||
|
||||
.. method:: setSource(imageMix)
|
||||
set image source
|
||||
|
||||
.. method:: setWeight(imageMix)
|
||||
set image source weight
|
||||
|
||||
.. attribute:: valid
|
||||
bool to tell if an image is available
|
||||
|
||||
.. class:: ImageRender(scene, camera)
|
||||
|
||||
Image source from render
|
||||
|
||||
.. attribute:: alpha
|
||||
use alpha in texture
|
||||
|
||||
.. attribute:: background
|
||||
background color
|
||||
|
||||
.. attribute:: capsize
|
||||
size of render area
|
||||
|
||||
.. attribute:: filter
|
||||
pixel filter
|
||||
|
||||
.. attribute:: flip
|
||||
flip image vertically
|
||||
|
||||
.. attribute:: image
|
||||
image data
|
||||
|
||||
.. method:: refresh(imageRender)
|
||||
Refresh image - invalidate its current content
|
||||
|
||||
.. attribute:: scale
|
||||
fast scale of image (near neighbour)
|
||||
|
||||
.. attribute:: size
|
||||
image size
|
||||
|
||||
.. attribute:: valid
|
||||
bool to tell if an image is available
|
||||
|
||||
.. attribute:: whole
|
||||
use whole viewport to render
|
||||
|
||||
.. class:: ImageViewport()
|
||||
|
||||
Image source from viewport
|
||||
|
||||
.. attribute:: alpha
|
||||
use alpha in texture
|
||||
|
||||
.. attribute:: capsize
|
||||
size of viewport area being captured
|
||||
|
||||
.. attribute:: filter
|
||||
pixel filter
|
||||
|
||||
.. attribute:: flip
|
||||
flip image vertically
|
||||
|
||||
.. attribute:: image
|
||||
image data
|
||||
|
||||
.. attribute:: position
|
||||
upper left corner of captured area
|
||||
|
||||
.. method:: refresh(imageViewport)
|
||||
Refresh image - invalidate its current content
|
||||
|
||||
.. attribute:: scale
|
||||
fast scale of image (near neighbour)
|
||||
|
||||
.. attribute:: size
|
||||
image size
|
||||
|
||||
.. attribute:: valid
|
||||
bool to tell if an image is available
|
||||
|
||||
.. attribute:: whole
|
||||
use whole viewport to capture
|
||||
|
||||
.. class:: Texture(gameObj)
|
||||
|
||||
Texture objects
|
||||
|
||||
.. attribute:: bindId
|
||||
OpenGL Bind Name
|
||||
|
||||
.. method:: close(texture)
|
||||
Close dynamic texture and restore original
|
||||
|
||||
.. attribute:: mipmap
|
||||
mipmap texture
|
||||
|
||||
.. method:: refresh(texture)
|
||||
Refresh texture from source
|
||||
|
||||
.. attribute:: source
|
||||
source of texture
|
||||
|
||||
.. class:: FilterBGR24()
|
||||
|
||||
Source filter BGR24 objects
|
||||
|
||||
.. class:: FilterBlueScreen()
|
||||
|
||||
Filter for Blue Screen objects
|
||||
|
||||
.. attribute:: color
|
||||
blue screen color
|
||||
|
||||
.. attribute:: limits
|
||||
blue screen color limits
|
||||
|
||||
.. attribute:: previous
|
||||
previous pixel filter
|
||||
|
||||
.. class:: FilterColor()
|
||||
|
||||
Filter for color calculations
|
||||
|
||||
.. attribute:: matrix
|
||||
matrix [4][5] for color calculation
|
||||
|
||||
.. attribute:: previous
|
||||
previous pixel filter
|
||||
|
||||
.. class:: FilterGray()
|
||||
|
||||
Filter for gray scale effect
|
||||
|
||||
.. attribute:: previous
|
||||
previous pixel filter
|
||||
|
||||
.. class:: FilterLevel()
|
||||
|
||||
Filter for levels calculations
|
||||
|
||||
.. attribute:: levels
|
||||
levels matrix [4] (min, max)
|
||||
|
||||
.. attribute:: previous
|
||||
previous pixel filter
|
||||
|
||||
.. class:: FilterNormal()
|
||||
|
||||
Filter for Blue Screen objects
|
||||
|
||||
.. attribute:: colorIdx
|
||||
index of color used to calculate normal (0 - red, 1 - green, 2 - blue)
|
||||
|
||||
.. attribute:: depth
|
||||
depth of relief
|
||||
|
||||
.. attribute:: previous
|
||||
previous pixel filter
|
||||
|
||||
.. class:: FilterRGB24()
|
||||
|
||||
Returns a new input filter object to be used with :class:'ImageBuff' object when the image passed
|
||||
to the ImageBuff.load() function has the 3-bytes pixel format BGR.
|
||||
|
||||
.. class:: FilterRGBA32()
|
||||
|
||||
Source filter RGBA32 objects
|
||||
|
||||
.. function:: getLastError()
|
||||
Last error that occurred in a bge.texture function.
|
||||
|
||||
:return: the description of the last error occurred in a bge.texture function.
|
||||
:rtype: string
|
||||
|
||||
.. function:: imageToArray(image,mode)
|
||||
Returns a :class:`~bgl.buffer` corresponding to the current image stored in a texture source object.
|
||||
|
||||
:arg image: Image source object.
|
||||
:type image: object of type :class:'VideoFFmpeg', :class:'ImageFFmpeg', :class:'ImageBuff', :class:'ImageMix', :class:'ImageRender', :class:'ImageMirror' or :class:'ImageViewport'
|
||||
:arg mode: optional argument representing the pixel format.
|
||||
| You can use the characters R, G, B for the 3 color channels, A for the alpha channel,
|
||||
| 0 to force a fixed 0 color channel and 1 to force a fixed 255 color channel.
|
||||
| Example: "BGR" will return 3 bytes per pixel with the Blue, Green and Red channels in that order.
|
||||
| "RGB1" will return 4 bytes per pixel with the Red, Green, Blue channels in that order and the alpha channel forced to 255.
|
||||
| The default mode is "RGBA".
|
||||
|
||||
:type mode: string
|
||||
:rtype: :class:`~bgl.buffer`
|
||||
:return: A object representing the image as one dimensional array of bytes of size (pixel_size*width*height),
|
||||
line by line starting from the bottom of the image. The pixel size and format is determined by the mode
|
||||
parameter.
|
||||
|
||||
.. function materialID(object,name)
|
||||
Returns a numeric value that can be used in :class:'Texture' to create a dynamic texture.
|
||||
|
||||
The value corresponds to an internal material number that uses the texture identified
|
||||
by name. name is a string representing a texture name with IM prefix if you want to
|
||||
identify the texture directly. This method works for basic tex face and for material,
|
||||
provided the material has a texture channel using that particular texture in first
|
||||
position of the texture stack. name can also have MA prefix if you want to identify
|
||||
the texture by material. In that case the material must have a texture channel in first
|
||||
position.
|
||||
|
||||
If the object has no material that matches name, it generates a runtime error. Use try/except to catch the exception.
|
||||
|
||||
Ex: bge.texture.materialID(obj, 'IMvideo.png')
|
||||
|
||||
:arg object: the game object that uses the texture you want to make dynamic
|
||||
:type object: game object
|
||||
:arg name: name of the texture/material you want to make dynamic.
|
||||
:type name: string
|
||||
:rtype: integer
|
||||
|
||||
.. function setLogFile(filename)
|
||||
Sets the name of a text file in which runtime error messages will be written, in addition to the printing
|
||||
of the messages on the Python console. Only the runtime errors specific to the VideoTexture module
|
||||
are written in that file, ordinary runtime time errors are not written.
|
||||
|
||||
:arg filename: name of error log file
|
||||
:type filename: string
|
||||
:rtype: integer
|
||||
Loading…
Reference in New Issue
Block a user