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)

1 files changed, 480 insertions, 0 deletions

diff --git a/doc/python_api/rst/bge.texture.rst b/doc/python_api/rst/bge.texture.rst
new file mode 100644
index 00000000000..b1ded95fc89
--- /dev/null
+++ b/doc/python_api/rst/bge.texture.rst
@@ -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