[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [38135] trunk/blender/doc/python_api/rst: patch [#27871] bge.texture documentation from Solano Fel?\195?\173cio ( + changes from me) it still needs work

[Dalai Felinto]

Revision: 38135
          http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=38135
Author:   dfelinto
Date:     2011-07-06 07:05:29 +0000 (Wed, 06 Jul 2011)
Log Message:
-----------
patch [#27871] bge.texture documentation from Solano Fel?\195?\173cio (+ 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)

Modified Paths:
--------------
    trunk/blender/doc/python_api/rst/bge.logic.rst

Added Paths:
-----------
    trunk/blender/doc/python_api/rst/bge.texture.rst

Modified: trunk/blender/doc/python_api/rst/bge.logic.rst
===================================================================
--- trunk/blender/doc/python_api/rst/bge.logic.rst	2011-07-06 01:34:10 UTC (rev 38134)
+++ trunk/blender/doc/python_api/rst/bge.logic.rst	2011-07-06 07:05:29 UTC (rev 38135)
@@ -17,7 +17,7 @@
    # 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
 

Added: trunk/blender/doc/python_api/rst/bge.texture.rst
===================================================================
--- trunk/blender/doc/python_api/rst/bge.texture.rst	                        (rev 0)
+++ trunk/blender/doc/python_api/rst/bge.texture.rst	2011-07-06 07:05:29 UTC (rev 38135)
@@ -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'

@@ Diff output truncated at 10240 characters. @@