+
+/*
+ * Convert a user's 2D image into a texture image. This basically repacks
+ * pixel data into the special texture formats used by core Mesa and the DRI
+ * drivers. This function can do full images or subimages.
+ *
+ * We return a boolean because this function may not accept some kinds of
+ * source image formats and/or types. For example, if the incoming
+ * format/type = GL_BGR, GL_UNSIGNED_INT this function probably won't
+ * be able to do the conversion.
+ *
+ * In that case, the incoming image should first be simplified to one of
+ * the "canonical" formats (GL_ALPHA, GL_LUMINANCE, GL_LUMINANCE_ALPHA,
+ * GL_INTENSITY, GL_RGB, GL_RGBA) and types (GL_CHAN). We can do that
+ * with the _mesa_transfer_teximage() function. That function will also
+ * do image transfer operations such as scale/bias and convolution.
+ *
+ * Input:
+ * mesaFormat - one of the MESA_FORMAT_* values from texformat.h
+ * xoffset, yoffset - position in dest image to put data
+ * width, height - incoming image size, also size of dest region.
+ * dstImageWidth - width (row stride) of dest image in pixels
+ * format, type - incoming image format and type
+ * packing - describes incoming image packing
+ * srcImage - pointer to source image
+ * destImage - pointer to dest image
+ */