BGE: bge.texture API documentation enhancement

This patch attempts to improve and review the documentation of bge.texture, as requested in the [[ http://wiki.blender.org/index.php/Dev:2.5/Source/Development/Todo/GameEngine#Video_Texture | TODO list ]].

More specifically, it

  - fixes the rst syntax, including titles of the examples bge.texture.py and bge.texture.1.py;

  - adds, standardizes and reviews description of the API elements, particularly signatures, types, etc.

  - adds SOURCE_* constants to the doc

  - splits the doc into thematical parts (Video, Image, Texture, and Filter Classes, Functions, Constants).

Notes:

  - The parameter "mode" of ImageBuff.plot has to be described better. Actually, the whole set of IMB_BLEND_* constants (from IMB_imbuf.h) should be exposed to Python. I'll do that in a future diff, and complete the doc at the same moment (adding those IMB_BLEND_* constants to the Constants part of this doc).

  - The option of using webcams in VideoFFmpeg is still particularly not well documented. I am planning to make a proposal about fixing T18634 (and its corresponding TODO in the list) by integrating OpenCV in the BGE (and Blender?). The idea would then probably be to add a new class, f.ex. ImageWebcam, making this functionnality more specialized. So for now I don't think it is worth to document that part much.

This patch fixes T44284 too.

Reviewers: moguri, kupoman, campbellbarton, panzergame, lordloki

Reviewed By: panzergame, lordloki

Subscribers: hg1

Projects: #game_engine, #game_python, #documentation

Maniphest Tasks: T44284

Differential Revision: https://developer.blender.org/D1352

doc/python_api/examples/bge.texture.1.py

@@ -2,8 +2,8 @@
 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.
+``createTexture()`` and ``removeTexture()`` are to be called from a
+module Python Controller.
 """
 from bge import logic
 from bge import texture

doc/python_api/examples/bge.texture.py

@@ -1,7 +1,8 @@
 """
 Basic Video Playback
 ++++++++++++++++++++
-Example of how to replace a texture in game with a video. It needs to run everyframe
+Example of how to replace a texture in game with a video. It needs to run
+everyframe.
 """
 import bge
 from bge import texture

source/gameengine/VideoTexture/blendVideoTex.cpp

@@ -50,6 +50,12 @@
 
 #include "Exception.h"
 
+// access to IMB_BLEND_* constants
+extern "C"
+{
+#include "IMB_imbuf.h"
+};
+
 
 // get material id
 static PyObject *getMaterialID (PyObject *self, PyObject *args)
@@ -208,7 +214,36 @@ PyMODINIT_FUNC initVideoTexturePythonBinding(void)
 	PyModule_AddIntConstant(m, "SOURCE_READY", SourceReady);
 	PyModule_AddIntConstant(m, "SOURCE_PLAYING", SourcePlaying);
 	PyModule_AddIntConstant(m, "SOURCE_STOPPED", SourceStopped);
-	
+
+	PyModule_AddIntConstant(m, "IMB_BLEND_MIX", IMB_BLEND_MIX);
+	PyModule_AddIntConstant(m, "IMB_BLEND_ADD", IMB_BLEND_ADD);
+	PyModule_AddIntConstant(m, "IMB_BLEND_SUB", IMB_BLEND_SUB);
+	PyModule_AddIntConstant(m, "IMB_BLEND_MUL", IMB_BLEND_MUL);
+	PyModule_AddIntConstant(m, "IMB_BLEND_LIGHTEN", IMB_BLEND_LIGHTEN);
+	PyModule_AddIntConstant(m, "IMB_BLEND_DARKEN", IMB_BLEND_DARKEN);
+	PyModule_AddIntConstant(m, "IMB_BLEND_ERASE_ALPHA", IMB_BLEND_ERASE_ALPHA);
+	PyModule_AddIntConstant(m, "IMB_BLEND_ADD_ALPHA", IMB_BLEND_ADD_ALPHA);
+	PyModule_AddIntConstant(m, "IMB_BLEND_OVERLAY", IMB_BLEND_OVERLAY);
+	PyModule_AddIntConstant(m, "IMB_BLEND_HARDLIGHT", IMB_BLEND_HARDLIGHT);
+	PyModule_AddIntConstant(m, "IMB_BLEND_COLORBURN", IMB_BLEND_COLORBURN);
+	PyModule_AddIntConstant(m, "IMB_BLEND_LINEARBURN", IMB_BLEND_LINEARBURN);
+	PyModule_AddIntConstant(m, "IMB_BLEND_COLORDODGE", IMB_BLEND_COLORDODGE);
+	PyModule_AddIntConstant(m, "IMB_BLEND_SCREEN", IMB_BLEND_SCREEN);
+	PyModule_AddIntConstant(m, "IMB_BLEND_SOFTLIGHT", IMB_BLEND_SOFTLIGHT);
+	PyModule_AddIntConstant(m, "IMB_BLEND_PINLIGHT", IMB_BLEND_PINLIGHT);
+	PyModule_AddIntConstant(m, "IMB_BLEND_VIVIDLIGHT", IMB_BLEND_VIVIDLIGHT);
+	PyModule_AddIntConstant(m, "IMB_BLEND_LINEARLIGHT", IMB_BLEND_LINEARLIGHT);
+	PyModule_AddIntConstant(m, "IMB_BLEND_DIFFERENCE", IMB_BLEND_DIFFERENCE);
+	PyModule_AddIntConstant(m, "IMB_BLEND_EXCLUSION", IMB_BLEND_EXCLUSION);
+	PyModule_AddIntConstant(m, "IMB_BLEND_HUE", IMB_BLEND_HUE);
+	PyModule_AddIntConstant(m, "IMB_BLEND_SATURATION", IMB_BLEND_SATURATION);
+	PyModule_AddIntConstant(m, "IMB_BLEND_LUMINOSITY", IMB_BLEND_LUMINOSITY);
+	PyModule_AddIntConstant(m, "IMB_BLEND_COLOR", IMB_BLEND_COLOR);
+
+	PyModule_AddIntConstant(m, "IMB_BLEND_COPY", IMB_BLEND_COPY);
+	PyModule_AddIntConstant(m, "IMB_BLEND_COPY_RGB", IMB_BLEND_COPY_RGB);
+	PyModule_AddIntConstant(m, "IMB_BLEND_COPY_ALPHA", IMB_BLEND_COPY_ALPHA);
+
 	// init last error description
 	Exception::m_lastError = "";