Merging trunk up to r38167.

5 files changed, 564 insertions, 1 deletions

diff --git a/doc/python_api/examples/bge.texture.1.py b/doc/python_api/examples/bge.texture.1.py
new file mode 100644
index 00000000000..5b387c8659c
--- /dev/null
+++ b/doc/python_api/examples/bge.texture.1.py
@@ -0,0 +1,38 @@
+"""
+Texture replacement
+++++++++++++++++++++++
+Example of how to replace a texture in game with an external image.
+createTexture() and removeTexture() are to be called from a module Python
+Controller.
+"""
+import bge
+from bge import logic
+from bge import texture	
+
+def createTexture(cont):
+    """Create a new Dynamic Texture"""
+    object = cont.owner
+	
+    # get the reference pointer (ID) of the internal texture
+    ID = VT.materialID(obj, 'IMoriginal.png')
+	
+    # create a texture object 
+    object_texture = texture.Texture(object, ID)
+	
+    # create a new source with an external image
+    url = logic.expandPath("//newtexture.jpg")
+    new_source = texture.ImageFFmpeg(url)
+	
+    # the texture has to be stored in a permanent Python object
+    logic.texture = object_texture
+	
+    # update/replace the texture
+    logic.texture.source = new_source
+    logic.texture.refresh(False)
+
+def removeTexture(cont):
+    """Delete the Dynamic Texture, reversing back the final to its original state."""
+    try:
+        del logic.texture
+    except:
+        pass
diff --git a/doc/python_api/examples/bge.texture.py b/doc/python_api/examples/bge.texture.py
new file mode 100644
index 00000000000..b27c357b1ee
--- /dev/null
+++ b/doc/python_api/examples/bge.texture.py
@@ -0,0 +1,32 @@
+"""
+Basic Video Playback
+++++++++++++++++++++++
+Example of how to replace a texture in game with a video. It needs to run everyframe
+"""
+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 bge.logic 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)
\ No newline at end of file
diff --git a/doc/python_api/examples/blf.py b/doc/python_api/examples/blf.py
new file mode 100644
index 00000000000..c91b41bec36
--- /dev/null
+++ b/doc/python_api/examples/blf.py
@@ -0,0 +1,42 @@
+"""
+Hello World Text Example
+++++++++++++++++++++++++
+Blender Game Engine example of using the blf module. For this module to work we
+need to use the OpenGL wrapper :class:`~bgl` as well.
+"""
+# import game engine modules
+import bge
+from bge import render
+from bge import logic
+# import stand alone modules
+import bgl
+import blf
+
+def init():
+    """init function - runs once"""
+    # create a new font object, use external ttf file
+    font_path = logic.expandPath('//Zeyada.ttf')
+	# store the font indice - to use later
+    logic.font_id = blf.load(font_path)
+
+    # set the font drawing routine to run every frame   
+    scene = logic.getCurrentScene()
+    scene.post_draw=[write]
+
+def write():
+    """write on screen"""
+    width = render.getWindowWidth()
+    height = render.getWindowHeight()
+    
+    # OpenGL setup
+    bgl.glMatrixMode(bgl.GL_PROJECTION)
+    bgl.glLoadIdentity()
+    bgl.gluOrtho2D(0, width, 0, height)
+    bgl.glMatrixMode(bgl.GL_MODELVIEW)
+    bgl.glLoadIdentity()
+    
+    # BLF drawing routine
+    font_id = logic.font_id
+    blf.position(font_id, (width*0.2), (height*0.3), 0)
+    blf.size(font_id, 50, 72)
+    blf.draw(font_id, "Hello World")
diff --git a/doc/python_api/rst/bge.logic.rst b/doc/python_api/rst/bge.logic.rst
index 0af4a1184d6..f7163ea928e 100644
--- a/doc/python_api/rst/bge.logic.rst
+++ b/doc/python_api/rst/bge.logic.rst
@@ -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
index 00000000000..49016d1e03d
--- /dev/null
+++ b/doc/python_api/rst/bge.texture.rst
@@ -0,0 +1,451 @@
+
+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
+
+.. 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