new example for bge.texture, a basic texture replacement

fresh simple and didactic example straight from my bge book, enjoy it ;)
video texture documentation online ... tears dropping.

diff --git a/doc/python_api/examples/bge.texture.1.py b/doc/python_api/examples/bge.texture.1.py
new file mode 100644 (file)
index 0000000..5b387c8
--- /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