patch [#27871] bge.texture documentation from Solano FelĂ­cio (+ changes from me)...
authorDalai Felinto <dfelinto@gmail.com>
Wed, 6 Jul 2011 07:05:29 +0000 (07:05 +0000)
committerDalai Felinto <dfelinto@gmail.com>
Wed, 6 Jul 2011 07:05:29 +0000 (07:05 +0000)
... 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)

doc/python_api/rst/bge.logic.rst
doc/python_api/rst/bge.texture.rst [new file with mode: 0644]

index 0af4a1184d6cff20670aef013c3cbab1d028f815..f7163ea928e08104f1068790f5403b7f5c14bc40 100644 (file)
@@ -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
 
diff --git a/doc/python_api/rst/bge.texture.rst b/doc/python_api/rst/bge.texture.rst
new file mode 100644 (file)
index 0000000..b1ded95
--- /dev/null
@@ -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