Vuo
1.2.5
|
An image residing in GPU memory (GL Texture Object).
Classes | |
struct | _VuoImage |
An image residing in GPU memory (GL Texture Object), with an optional CPU copy. More... | |
Typedefs | |
typedef struct _VuoImage * | VuoImage |
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, void(^freeCallback)(void *pixels)) |
Uploads the specified pixel data to the GPU and returns a new VuoImage referencing it. | |
VuoImage | VuoImage_makeFromJson (json_object *js) |
Decodes the JSON object js to create a new value. | |
json_object * | VuoImage_getJson (const VuoImage value) |
Encodes value as a JSON object. | |
json_object * | VuoImage_getInterprocessJson (const VuoImage value) |
Returns a JSON object containing an interprocess handle for the specified texture. | |
char * | VuoImage_getSummary (const VuoImage value) |
A brief summary of the contents of this texture. | |
VuoImage | VuoImage_makeFromBufferWithStride (const void *pixels, unsigned int format, unsigned int pixelsWide, unsigned int pixelsHigh, unsigned int bytesPerRow, VuoImageColorDepth colorDepth, void(^freeCallback)(void *pixels)) __attribute__((nonnull(1))) |
Same as VuoImage_makeFromBuffer, but accepts a nonstandard stride (bytesPerRow ). | |
VuoImage | VuoImage_makeColorImage (VuoColor color, unsigned int pixelsWide, unsigned int pixelsHigh) |
Makes a solid-color image. | |
VuoImage | VuoImage_makeCopy (VuoImage image, bool flip) |
Returns a new texture copy of the passed image. | |
VuoImage | VuoImage_makeGlTextureRectangleCopy (VuoImage image) |
Copies image to a new GL_TEXTURE_RECTANGLE_ARB texture. | |
const unsigned char * | VuoImage_getBuffer (VuoImage image, unsigned int requestedFormat) |
Downloads the specified image's pixel data from the GPU to the CPU (or returns it from a cache), and returns the CPU memory buffer. | |
VuoImageWrapMode | VuoImage_getWrapMode (VuoImage image) |
Returns the image's wrap mode. | |
void | VuoImage_setWrapMode (VuoImage image, VuoImageWrapMode wrapMode) |
Changes the image's wrap mode. | |
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_areEqualWithinTolerance (const VuoImage a, const VuoImage b, const unsigned char tolerance) |
Like VuoImage_areEqual(), but permits color channel values to differ by up to tolerance . | |
bool | VuoImage_isEmpty (const VuoImage image) |
bool | VuoImage_isPopulated (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. | |
GLuint | VuoImage_resolveInterprocessJsonUsingTextureProvider (struct json_object *js, GLuint(^provider)(unsigned int pixelsWide, unsigned int pixelsHigh), unsigned int *outputPixelsWide, unsigned int *outputPixelsHigh, void *outputIOSurface) |
Decodes the JSON object js onto a host-provided OpenGL texture's GL_TEXTURE_RECTANGLE_ARB target. | |
VuoImage | VuoImage_makeFromString (const char *str) |
Automatically generated function. | |
char * | VuoImage_getString (const VuoImage value) |
Automatically generated function. | |
char * | VuoImage_getInterprocessString (const VuoImage value) |
Automatically generated function. | |
void | VuoImage_retain (VuoImage value) |
Automatically generated function. | |
void | VuoImage_release (VuoImage value) |
Automatically generated function. | |
struct _VuoImage |
Class Members | ||
---|---|---|
struct json_object * | cpuData |
Map of GL formats to their char * pixelbuffers and freeCallbacks. |
dispatch_queue_t | cpuQueue |
Serializes access to cpuData . |
dispatch_once_t | cpuQueueInitialized |
Has cpuQueue been initialized? |
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. |
float | scaleFactor | Number of linear pixels per point in this image. scaleFactor=1 for @1x images, 2 for @2x (Retina) images. |
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).
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.
bool VuoImage_areEqualWithinTolerance | ( | const VuoImage | a, |
const VuoImage | b, | ||
const unsigned char | tolerance | ||
) |
Like VuoImage_areEqual(), but permits color channel values to differ by up to tolerance
.
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.
const unsigned char* VuoImage_getBuffer | ( | VuoImage | image, |
unsigned int | requestedFormat | ||
) |
Downloads the specified image's pixel data from the GPU to the CPU (or returns it from a cache), 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 returned buffer is owned by the VuoImage instance; the caller should not modify or free()
it.
This function may be called from any thread.
image | The image to download. |
requestedFormat | An OpenGL format constant. Supported formats include:
|
VuoImageColorDepth VuoImage_getColorDepth | ( | const VuoImage | image | ) |
Returns the color depth of the image.
|
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_getInterprocessString | ( | const VuoImage | value | ) |
Automatically generated function.
|
read |
Encodes value
as a JSON object.
This function may be called from any thread.
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.
char* VuoImage_getString | ( | const VuoImage | value | ) |
Automatically generated function.
char * VuoImage_getSummary | ( | const VuoImage | value | ) |
A brief summary of the contents of this texture.
This function may be called from any thread.
VuoImageWrapMode VuoImage_getWrapMode | ( | VuoImage | image | ) |
Returns the image's wrap mode.
bool VuoImage_isEmpty | ( | const VuoImage | image | ) |
bool VuoImage_isPopulated | ( | const VuoImage | image | ) |
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:
GL_TEXTURE_2D
.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:
GL_TEXTURE_2D
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. freeCallback
must not be NULL.
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:
GL_TEXTURE_RECTANGLE_ARB
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. freeCallback
must not be NULL.
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.
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.
Returns a new texture copy of the passed image.
image
may be either GL_TEXTURE_2D
or GL_TEXTURE_RECTANGLE_ARB
.
If flip
is true, the copied image is flipped upside-down relative to the source image.
VuoImage VuoImage_makeFromBuffer | ( | const void * | pixels, |
unsigned int | format, | ||
unsigned int | pixelsWide, | ||
unsigned int | pixelsHigh, | ||
VuoImageColorDepth | colorDepth, | ||
void(^)(void *pixels) | freeCallback | ||
) |
Uploads the specified pixel data to the GPU and returns a new VuoImage referencing it.
This function may be called from any thread.
pixels | Pointer to a buffer of pixel data. Row-major, starting at the bottom (flipped). Zero stride. Premultiplied alpha. Vuo takes ownership of this data, and will invoke freeCallback when it's done using it. |
format | An OpenGL format constant. Supported formats include:
|
pixelsWide | Width in pixels |
pixelsHigh | Height in pixels |
colorDepth | The number of bits per channel. When 8bpc, pixels should be unsigned char * ; when 16bpc, pixels should be float * . |
freeCallback |
VuoImage VuoImage_makeFromBufferWithStride | ( | const void * | pixels, |
unsigned int | format, | ||
unsigned int | pixelsWide, | ||
unsigned int | pixelsHigh, | ||
unsigned int | bytesPerRow, | ||
VuoImageColorDepth | colorDepth, | ||
void(^)(void *pixels) | freeCallback | ||
) |
Same as VuoImage_makeFromBuffer, but accepts a nonstandard stride (bytesPerRow
).
VuoImage VuoImage_makeFromJson | ( | 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.
js
contains valid data, returns a pointer to the VuoImage. If not, returns NULL.js | A JSON object containing one of the following schemas: |
VuoImage:
IOSurfaceID
and the texture's width and height in pixels: VuoImage VuoImage_makeFromString | ( | const char * | str | ) |
Automatically generated function.
Copies image
to a new GL_TEXTURE_RECTANGLE_ARB
texture.
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.
GLuint VuoImage_resolveInterprocessJsonUsingTextureProvider | ( | struct json_object * | js, |
GLuint(^)(unsigned int pixelsWide, unsigned int pixelsHigh) | provider, | ||
unsigned int * | outputPixelsWide, | ||
unsigned int * | outputPixelsHigh, | ||
void * | outputIOSurface | ||
) |
Decodes the JSON object js
onto a host-provided OpenGL texture's GL_TEXTURE_RECTANGLE_ARB
target.
js
contains valid data, returns the OpenGL texture name. If not, returns 0.js | An interprocess JSON object containing an ioSurface . | |
provider | A block that returns an OpenGL texture name with the requested width and height. The host app must not call glTexImage2D() on the texture, since this makes the texture incompatible with the IOSurface backing. | |
[out] | outputPixelsWide | Upon return, this contains the width of the output texture. |
[out] | outputPixelsHigh | Upon return, this contains the height of the output texture. |
[out] | outputIOSurface | Upon return, this contains the IOSurface backing the output texture. When the host app is finished with the output texture, it must signal and release the IOSurface: VuoIoSurfacePool_signal(outputIOSurface); CFRelease(outputIOSurface); |
This function may be called from any thread.
void VuoImage_retain | ( | VuoImage | value | ) |
Automatically generated function.
void VuoImage_setWrapMode | ( | VuoImage | image, |
VuoImageWrapMode | wrapMode | ||
) |
Changes the image's wrap mode.