Vuo  0.9.1
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
Classes | Typedefs | Functions

Description

An image residing in GPU memory (GL Texture Object).

Classes

struct  _VuoImage
 An image residing in GPU memory (GL Texture Object). More...
 

Typedefs

typedef struct _VuoImageVuoImage
 An image residing in GPU memory (GL Texture Object).
 
typedef void(* VuoImage_freeCallback )(VuoImage imageToFree)
 A callback to be implemented if non-Vuo code needs to retain ownership of the GL texture (instead of the default behavior where VuoImage takes ownership of the texture).
 

Functions

VuoImage VuoImage_get (const char *imageURL)
 Retrieves the image at the specified imageURL, and creates a VuoImage from it.
 
void VuoImage_free (void *texture)
 Decrements the retain count of the OpenGL Texture Object associated with the specified VuoImage, and frees the texture VuoImage struct.
 
VuoImage VuoImage_make (unsigned int glTextureName, unsigned int glInternalFormat, unsigned long int pixelsWide, unsigned long int pixelsHigh)
 Returns a new VuoImage structure representing the specified glTextureName.
 
VuoImage VuoImage_makeClientOwned (unsigned int glTextureName, unsigned int glInternalFormat, unsigned long int pixelsWide, unsigned long int pixelsHigh, VuoImage_freeCallback freeCallback, void *freeCallbackContext)
 Returns a new VuoImage structure representing the specified glTextureName.
 
VuoImage VuoImage_makeClientOwnedGlTextureRectangle (unsigned int glTextureName, unsigned int glInternalFormat, unsigned long int pixelsWide, unsigned long int pixelsHigh, VuoImage_freeCallback freeCallback, void *freeCallbackContext)
 Returns a new VuoImage structure representing the specified glTextureName.
 
VuoImage VuoImage_makeFromBuffer (const void *pixels, unsigned int format, unsigned int pixelsWide, unsigned int pixelsHigh, VuoImageColorDepth colorDepth)
 Uploads the specified pixel data to the GPU and returns a new VuoImage referencing it.
 
VuoImage VuoImage_valueFromJson (json_object *js)
 Decodes the JSON object js to create a new value.
 
json_object * VuoImage_jsonFromValue (const VuoImage value)
 Encodes value as a JSON object.
 
json_object * VuoImage_interprocessJsonFromValue (const VuoImage value)
 Returns a JSON object containing an interprocess handle for the specified texture.
 
char * VuoImage_summaryFromValue (const VuoImage value)
 A brief summary of the contents of this texture.
 
VuoImage VuoImage_makeColorImage (VuoColor color, unsigned int pixelsWide, unsigned int pixelsHigh)
 Makes a solid-color image.
 
VuoImage VuoImage_makeCopy (VuoImage image)
 Returns a new texture copy of the passed image.
 
VuoImage VuoImage_makeGlTextureRectangleCopy (VuoImage image)
 Copies image to a new GL_TEXTURE_RECTANGLE_ARB texture.
 
unsigned char * VuoImage_copyBuffer (VuoImage image, unsigned int requestedFormat)
 Downloads the specified image's pixel data from the GPU to the CPU, and returns the CPU memory buffer.
 
void VuoImage_setWrapMode (VuoImage image, VuoImageWrapMode wrapMode)
 Changes the image's wrap mode.
 
VuoImage VuoImage_blur (VuoImage image, VuoReal radius, VuoBoolean expandBounds)
 Returns a blurred copy of image.
 
VuoImage VuoImage_mapColors (VuoImage image, VuoList_VuoColor colors, VuoReal filterOpacity)
 Returns a color-mapped copy of image.
 
bool VuoImage_areEqual (const VuoImage a, const VuoImage b)
 Returns true if both images have the same dimensions and the same RGBA pixel data.
 
bool VuoImage_isEmpty (const VuoImage image)
 
VuoRectangle VuoImage_getRectangle (const VuoImage image)
 Returns a rectangle (in Vuo Coordinates) at the origin, with width 2 and height matching the image's aspect ratio.
 
VuoImageColorDepth VuoImage_getColorDepth (const VuoImage image)
 Returns the color depth of the image.
 
VuoImage VuoImage_valueFromString (const char *str)
 Automatically generated function.
 
char * VuoImage_stringFromValue (const VuoImage value)
 Automatically generated function.
 
char * VuoImage_interprocessStringFromValue (const VuoImage value)
 Automatically generated function.
 
void VuoImage_retain (VuoImage value)
 Automatically generated function.
 
void VuoImage_release (VuoImage value)
 Automatically generated function.
 

Class Documentation

struct _VuoImage
Class Members
VuoImage_freeCallback freeCallback A callback to be implemented if non-Vuo code needs to retain ownership of the GL texture. See VuoImage_makeClientOwned.
void * freeCallbackContext User data for freeCallback. See VuoImage_makeClientOwned.
unsigned int glInternalFormat The OpenGL internal texture format (as provided to glTexImage2D).
unsigned int glTextureName The unique OpenGL texture identifier.
unsigned long int glTextureTarget Always GL_TEXTURE_2D, unless converting from an IOSurface.
unsigned long int pixelsHigh The vertical size of the image, in pixels.
unsigned long int pixelsWide The horizontal size of the image, in pixels.

Typedef Documentation

typedef struct _VuoImage* VuoImage

An image residing in GPU memory (GL Texture Object).

The struct is typedef'd to a pointer so that VuoImages are reference-counted, enabling us to automatically delete the GL Texture Object when the last reference is released.

typedef void(* VuoImage_freeCallback)(VuoImage imageToFree)

A callback to be implemented if non-Vuo code needs to retain ownership of the GL texture (instead of the default behavior where VuoImage takes ownership of the texture).

See Also
VuoImage_makeClientOwned

Function Documentation

bool VuoImage_areEqual ( const VuoImage  a,
const VuoImage  b 
)

Returns true if both images have the same dimensions and the same RGBA pixel data.

Other attributes (pixel format, target) are ignored.

Two NULL images are considered equal. A NULL image is never equal to a non-NULL image.

This operation is fairly expensive — it requires downloading both images from the GPU to the CPU. It's intended primarily for use in automated tests.

VuoImage VuoImage_blur ( VuoImage  image,
VuoReal  radius,
VuoBoolean  expandBounds 
)

Returns a blurred copy of image.

(Or, if radius is zero, returns image.)

If expandBounds is true, the output image will be expanded to encompass the full bleed of the blur. Otherwise, the output image will have the same dimensions as the soure image.

unsigned char* VuoImage_copyBuffer ( VuoImage  image,
unsigned int  requestedFormat 
)

Downloads the specified image's pixel data from the GPU to the CPU, and returns the CPU memory buffer.

The return value is a pointer to a buffer of pixel data. 8 bits per channel. Row-major, starting at the bottom (flipped). Zero stride. Premultiplied alpha.

The caller should free() the returned buffer when it is finished using it.

This function may be called from any thread.

Parameters
imageThe image to download.
requestedFormatAn OpenGL format constant. Supported formats include:
  • GL_RGBA (32 bits per pixel)
  • GL_BGRA (32 bits per pixel)
  • GL_LUMINANCE (8 bits per pixel)
  • GL_LUMINANCE_ALPHA (16 bits per pixel)
void VuoImage_free ( void *  texture)

Decrements the retain count of the OpenGL Texture Object associated with the specified VuoImage, and frees the texture VuoImage struct.

This function may be called from any thread.

VuoImage VuoImage_get ( const char *  imageURL)

Retrieves the image at the specified imageURL, and creates a VuoImage from it.

This function may be called from any thread.

VuoImageColorDepth VuoImage_getColorDepth ( const VuoImage  image)

Returns the color depth of the image.

VuoRectangle VuoImage_getRectangle ( const VuoImage  image)

Returns a rectangle (in Vuo Coordinates) at the origin, with width 2 and height matching the image's aspect ratio.

struct json_object * VuoImage_interprocessJsonFromValue ( const VuoImage  value)
read

Returns a JSON object containing an interprocess handle for the specified texture.

value may be either GL_TEXTURE_2D or GL_TEXTURE_RECTANGLE_ARB.

This function may be called from any thread.

char* VuoImage_interprocessStringFromValue ( const VuoImage  value)

Automatically generated function.

bool VuoImage_isEmpty ( const VuoImage  image)
  • If either image dimension is 0, returns true.
  • If the image is fully transparent (all pixels have alpha value 0), returns true.
  • Otherwise returns false.
struct json_object * VuoImage_jsonFromValue ( const VuoImage  value)
read

Encodes value as a JSON object.

This function may be called from any thread.

VuoImage VuoImage_make ( unsigned int  glTextureName,
unsigned int  glInternalFormat,
unsigned long int  pixelsWide,
unsigned long int  pixelsHigh 
)

Returns a new VuoImage structure representing the specified glTextureName.

The texture must:

  • be of type GL_TEXTURE_2D.
  • use wrap mode GL_CLAMP_TO_BORDER on the S and T axes
  • use minifying and magnification filter GL_LINEAR

The VuoImage takes ownership of glTextureName, and will call glDeleteTextures() on it when it's no longer needed.

VuoImage is intended to be immutable — do not modify the contents of the glTextureName after passing it to this function.

This function may be called from any thread.

VuoImage VuoImage_makeClientOwned ( unsigned int  glTextureName,
unsigned int  glInternalFormat,
unsigned long int  pixelsWide,
unsigned long int  pixelsHigh,
VuoImage_freeCallback  freeCallback,
void *  freeCallbackContext 
)

Returns a new VuoImage structure representing the specified glTextureName.

The texture must:

  • be of type GL_TEXTURE_2D
  • use wrap mode GL_CLAMP_TO_BORDER on the S and T axes
  • use minifying and magnification filter GL_LINEAR

When the VuoImage is no longer needed, freeCallback is called. The freeCallback may then activate a GL context and delete the texture, or send it back to a texture pool.

freeCallbackContext is optional data passed to freeCallback via the VuoImage struct. Use NULL if you don't need to provide additional data to the callback.

VuoImage is intended to be immutable — do not modify the contents of the glTextureName between passing it to this function and when freeCallback is called.

This function may be called from any thread.

VuoImage VuoImage_makeClientOwnedGlTextureRectangle ( unsigned int  glTextureName,
unsigned int  glInternalFormat,
unsigned long int  pixelsWide,
unsigned long int  pixelsHigh,
VuoImage_freeCallback  freeCallback,
void *  freeCallbackContext 
)

Returns a new VuoImage structure representing the specified glTextureName.

The texture must:

  • be of type GL_TEXTURE_RECTANGLE_ARB
  • use wrap mode GL_CLAMP_TO_BORDER on the S and T axes
  • use minifying and magnification filter GL_LINEAR

When the VuoImage is no longer needed, freeCallback is called. The freeCallback may then activate a GL context and delete the texture, or send it back to a texture pool.

freeCallbackContext is optional data passed to freeCallback via the VuoImage struct. Use NULL if you don't need to provide additional data to the callback.

VuoImage is intended to be immutable — do not modify the contents of the glTextureName between passing it to this function and when freeCallback is called.

Note
Images returned by this function may only be passed to functions that explicitly mention support for GL_TEXTURE_RECTANGLE_ARB.

This function may be called from any thread.

VuoImage VuoImage_makeColorImage ( VuoColor  color,
unsigned int  pixelsWide,
unsigned int  pixelsHigh 
)

Makes a solid-color image.

VuoImage VuoImage_makeCopy ( VuoImage  image)

Returns a new texture copy of the passed image.

image may be either GL_TEXTURE_2D or GL_TEXTURE_RECTANGLE_ARB.

VuoImage VuoImage_makeFromBuffer ( const void *  pixels,
unsigned int  format,
unsigned int  pixelsWide,
unsigned int  pixelsHigh,
VuoImageColorDepth  colorDepth 
)

Uploads the specified pixel data to the GPU and returns a new VuoImage referencing it.

This function may be called from any thread.

Parameters
pixelsPointer to a buffer of pixel data. Row-major, starting at the bottom (flipped). Zero stride. Premultiplied alpha. The caller is responsible for freeing this buffer sometime after this function returns.
formatAn OpenGL format constant. Supported formats include:
  • GL_RGB
  • GL_YCBCR_422_APPLE
  • GL_RGBA
  • GL_BGRA
  • GL_LUMINANCE
  • GL_LUMINANCE_ALPHA
pixelsWideWidth in pixels
pixelsHighHeight in pixels
colorDepthThe number of bits per channel. When 8bpc, pixels should be unsigned char *; when 16bpc, pixels should be float *.
VuoImage VuoImage_makeGlTextureRectangleCopy ( VuoImage  image)

Copies image to a new GL_TEXTURE_RECTANGLE_ARB texture.

Note
This is intended for interfacing with host apps; Vuo should always use GL_TEXTURE_2D internally.
VuoImage VuoImage_mapColors ( VuoImage  image,
VuoList_VuoColor  colors,
VuoReal  filterOpacity 
)

Returns a color-mapped copy of image.

(Or, if colors is empty, returns image.)

void VuoImage_release ( VuoImage  value)

Automatically generated function.

void VuoImage_retain ( VuoImage  value)

Automatically generated function.

void VuoImage_setWrapMode ( VuoImage  image,
VuoImageWrapMode  wrapMode 
)

Changes the image's wrap mode.

char* VuoImage_stringFromValue ( const VuoImage  value)

Automatically generated function.

char * VuoImage_summaryFromValue ( const VuoImage  value)

A brief summary of the contents of this texture.

This function may be called from any thread.

Example:
GL Texture (ID 42)
640x480
VuoImage VuoImage_valueFromJson ( json_object *  js)

Decodes the JSON object js to create a new value.

Automatically activates and deactivates a GL Context (if needed to dereference an IOSurface).

This function may be called from any thread.

Returns
If js contains valid data, returns a pointer to the VuoImage. If not, returns NULL.
Parameters
jsA JSON object containing one of the following schemas:
  • a GL Texture Name, format, and the texture's width and height in pixels:
    Example:
    {
    "glTextureName": 42,
    "glInternalFormat": 6407,
    "pixelsWide": 640,
    "pixelsHigh": 480
    }
  • an IOSurfaceID and the texture's width and height in pixels:
    Example:
    {
    "ioSurface": 42,
    "pixelsWide": 640,
    "pixelsHigh": 480
    }
  • a color and the texture's width and height in pixels:
    Example:
    {
    "color": {"r":0.5, "g":1, "b":0, "a":1},
    "pixelsWide": 640,
    "pixelsHigh": 480
    }
Todo:
candidate for VuoShader_makeGlTextureRectangleShader()?
VuoImage VuoImage_valueFromString ( const char *  str)

Automatically generated function.