VideoTexture: improvements to image data access API.

- Use BGL buffer instead of string for image data.
- Add buffer interface to image source.
- Allow customization of pixel format.
- Add valid property to check if the image data is available.

The image property of all Image source objects will now
return a BGL 'buffer' object. Previously it was returning
a string, which was not working at all with Python 3.1.
The BGL buffer type allows sequence access to bytes and
is directly usable in BGL OpenGL wrapper functions.
The buffer is formated as a 1 dimensional array of bytes
with 4 bytes per pixel in RGBA order.

BGL buffers will also be accepted in the ImageBuff load()
and plot() functions.

It is possible to customize the pixel format by using
the VideoTexture.imageToArray(image, mode) function:
the first argument is a Image source object, the second
optional argument is a format string using the R, G, B,
A, 0 and 1 characters. For example "BGR" means that each
pixel will be 3 bytes, corresponding to the Blue, Green
and Red channel in that order. Use 0 for a fixed hex 00
value, 1 for hex FF. The default mode is "RGBA".

All Image source objects now support the buffer interface
which allows to create memoryview objects for direct access
to the image internal buffer without memory copy. The buffer
format is one dimensional array of bytes with 4 bytes per
pixel in RGBA order. The buffer is writable, which allows
custom modifications of the image data.

v = memoryview(source)

A bug in the Python 3.1 buffer API will cause a crash if
the memoryview object cannot be created. Therefore, you
must always check first that an image data is available
before creating a memoryview object. Use the new valid
attribute for that:

if source.valid:
    v = memoryview(source)
    ...	

Note: the BGL buffer object itself does not yet support
the buffer interface.

Note: the valid attribute makes sense only if you use
image source in conjunction with texture object like this:

# refresh texture but keep image data in memory
texture.refresh(False)
if texture.source.valid:
    v = memoryview(texture.source)
    # process image
    ...
    # invalidate image for next texture refresh
    texture.source.refresh()

Limitation: While memoryview objects exist, the image cannot be
resized. Resizing occurs with ImageViewport objects when the
viewport size is changed or with ImageFFmpeg when a new image
is reloaded for example. Any attempt to resize will cause a
runtime error. Delete the memoryview objects is you want to
resize an image source object.

1 files changed, 83 insertions, 19 deletions

diff --git a/source/gameengine/VideoTexture/ImageBuff.cpp b/source/gameengine/VideoTexture/ImageBuff.cpp
index eccac9d9f89..474a34b2f43 100644
--- a/source/gameengine/VideoTexture/ImageBuff.cpp
+++ b/source/gameengine/VideoTexture/ImageBuff.cpp
@@ -26,7 +26,7 @@ http://www.gnu.org/copyleft/lesser.txt.
 #include <structmember.h>
 
 #include "ImageBuff.h"
-
+#include "Exception.h"
 #include "ImageBase.h"
 #include "FilterSource.h"
 
@@ -34,6 +34,7 @@ http://www.gnu.org/copyleft/lesser.txt.
 extern "C" {
 #include "IMB_imbuf_types.h"
 #include "IMB_imbuf.h"
+#include "BGL.h"
 };
 
 // default filter
@@ -137,7 +138,7 @@ static bool testPyBuffer(Py_buffer* buffer, int width, int height, unsigned int
 	} 
 	if (buffer->len != width*height*pixsize)
 	{
-		PyErr_SetString(PyExc_ValueError, "Buffer hasn't correct size");
+		PyErr_SetString(PyExc_ValueError, "Buffer hasn't the correct size");
 		return false;
 	} 
 	// multi dimension are ok as long as there is no hole in the memory
@@ -160,43 +161,91 @@ static bool testPyBuffer(Py_buffer* buffer, int width, int height, unsigned int
 	return true;
 }
 
+static bool testBGLBuffer(Buffer* buffer, int width, int height, unsigned int pixsize)
+{
+	unsigned int size = BGL_typeSize(buffer->type);
+	for (int i=0; i<buffer->ndimensions; i++)
+	{
+		size *= buffer->dimensions[i];
+	}
+	if (size != width*height*pixsize)
+	{
+		PyErr_SetString(PyExc_ValueError, "Buffer hasn't the correct size");
+		return false;
+	} 
+	return true;
+}
+
+
 // load image
 static PyObject * load (PyImage * self, PyObject * args)
 {
 	// parameters: string image buffer, its size, width, height
 	Py_buffer buffer;
+	Buffer *bglBuffer;
 	short width;
 	short height;
+	unsigned int pixSize;
+
+	// calc proper buffer size
+	// use pixel size from filter
+	if (self->m_image->getFilter() != NULL)
+		pixSize = self->m_image->getFilter()->m_filter->firstPixelSize();
+	else
+		pixSize = defFilter.firstPixelSize();
+
 	// parse parameters
 	if (!PyArg_ParseTuple(args, "s*hh:load", &buffer, &width, &height))
 	{
-		// report error
-		return NULL;
+		PyErr_Clear();
+		// check if it is BGL buffer
+		if (!PyArg_ParseTuple(args, "O!hh:load", &BGL_bufferType, &bglBuffer, &width, &height))
+		{
+			// report error
+			return NULL;
+		}
+		else
+		{
+			if (testBGLBuffer(bglBuffer, width, height, pixSize))
+			{
+				try
+				{
+					// if correct, load image
+					getImageBuff(self)->load((unsigned char*)bglBuffer->buf.asvoid, width, height);
+				}
+				catch (Exception & exp)
+				{
+					exp.report();
+				}
+			}
+		}
 	}
-	// else check buffer size
 	else
 	{
-		// calc proper buffer size
-		unsigned int pixSize;
-		// use pixel size from filter
-		if (self->m_image->getFilter() != NULL)
-			pixSize = self->m_image->getFilter()->m_filter->firstPixelSize();
-		else
-			pixSize = defFilter.firstPixelSize();
 		// check if buffer size is correct
 		if (testPyBuffer(&buffer, width, height, pixSize))
 		{
-			// if correct, load image
-			getImageBuff(self)->load((unsigned char*)buffer.buf, width, height);
+			try 
+			{
+				// if correct, load image
+				getImageBuff(self)->load((unsigned char*)buffer.buf, width, height);
+			}
+			catch (Exception & exp)
+			{
+				exp.report();
+			}
 		}
 		PyBuffer_Release(&buffer);
 	}
+	if (PyErr_Occurred())
+		return NULL;
 	Py_RETURN_NONE;	
 }
 
 static PyObject * plot (PyImage * self, PyObject * args)
 {
 	PyImage * other;
+	Buffer* bglBuffer;
 	Py_buffer buffer;
 	//unsigned char * buff;
 	//unsigned int buffSize;
@@ -214,17 +263,31 @@ static PyObject * plot (PyImage * self, PyObject * args)
 			getImageBuff(self)->plot((unsigned char*)buffer.buf, width, height, x, y, mode);
 		}
 		PyBuffer_Release(&buffer);
+		if (PyErr_Occurred())
+			return NULL;
 		Py_RETURN_NONE;	
 	}
 	PyErr_Clear();
 	// try the other format
-	if (!PyArg_ParseTuple(args, "O!hh|h:plot", &ImageBuffType, &other, &x, &y, &mode))
+	if (PyArg_ParseTuple(args, "O!hh|h:plot", &ImageBuffType, &other, &x, &y, &mode))
 	{
-		PyErr_SetString(PyExc_TypeError, "Expecting ImageBuff or string,width,height as first arguments, postion x, y and mode and last arguments");
+		getImageBuff(self)->plot(getImageBuff(other), x, y, mode);
+		Py_RETURN_NONE;
+	}
+	PyErr_Clear();
+	// try the last format (BGL buffer)
+	if (!PyArg_ParseTuple(args, "O!hhhh|h:plot", &BGL_bufferType, &bglBuffer, &width, &height, &x, &y, &mode))
+	{
+		PyErr_SetString(PyExc_TypeError, "Expecting ImageBuff or Py buffer or BGL buffer as first argument; width, height next; postion x, y and mode as last arguments");
 		return NULL;
 	}
-	getImageBuff(self)->plot(getImageBuff(other), x, y, mode);
-	Py_RETURN_NONE;
+	if (testBGLBuffer(bglBuffer, width, height, 4))
+	{
+		getImageBuff(self)->plot((unsigned char*)bglBuffer->buf.asvoid, width, height, x, y, mode);
+	}
+	if (PyErr_Occurred)
+		return NULL;
+	Py_RETURN_NONE;	
 }
 
 // methods structure
@@ -237,6 +300,7 @@ static PyMethodDef imageBuffMethods[] =
 // attributes structure
 static PyGetSetDef imageBuffGetSets[] =
 {	// attributes from ImageBase class
+	{(char*)"valid", (getter)Image_valid, NULL, (char*)"bool to tell if an image is available", NULL},
 	{(char*)"image", (getter)Image_getImage, NULL, (char*)"image data", NULL},
 	{(char*)"size", (getter)Image_getSize, NULL, (char*)"image size", NULL},
 	{(char*)"scale", (getter)Image_getScale, (setter)Image_setScale, (char*)"fast scale of image (near neighbour)", NULL},
@@ -267,7 +331,7 @@ PyTypeObject ImageBuffType =
 	0,                         /*tp_str*/
 	0,                         /*tp_getattro*/
 	0,                         /*tp_setattro*/
-	0,                         /*tp_as_buffer*/
+	&imageBufferProcs,         /*tp_as_buffer*/
 	Py_TPFLAGS_DEFAULT,        /*tp_flags*/
 	"Image source from image buffer",       /* tp_doc */
 	0,		               /* tp_traverse */