Vuo 2.4.4
|
An image residing in GPU memory (GL Texture Object).
Macros | |
#define | VuoImage_SUPPORTS_COMPARISON |
Instances of this type can be compared and sorted. | |
#define | VuoImage_OVERRIDES_INTERPROCESS_SERIALIZATION |
This type implements _getInterprocessJson() . | |
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). | |
Enumerations | |
enum | VuoImageSamplingMode { VuoImageSampling_Nearest , VuoImageSampling_Linear } |
Different types of image interpolation. More... | |
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. | |
VuoImage | VuoImage_makeFromJsonWithDimensions (struct json_object *js, unsigned int requestedPixelsWide, unsigned int requestedPixelsHigh) |
Decodes the JSON object js to create a new VuoImage. | |
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))) __attribute__((nonnull(7))) |
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, unsigned int forcePixelsWide, unsigned int forcePixelsHigh, bool forceAlpha) |
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. | |
void | VuoImage_setSamplingMode (VuoImage image, VuoImageSamplingMode samplingMode) |
Changes the image's sampling 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_isLessThan (const VuoImage a, const VuoImage b) |
Returns true if the size of a is less than the size of b . | |
bool | VuoImage_isEmpty (const VuoImage image) |
bool | VuoImage_isBlackOrTransparent (const VuoImage image, const unsigned char tolerance) |
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) VuoWarnUnusedResult |
Decodes the JSON object js onto a host-provided OpenGL texture's GL_TEXTURE_RECTANGLE_ARB target. | |
bool | VuoImage_resolveInterprocessJsonUsingClientTexture (struct json_object *js, GLuint textureName, unsigned int pixelsWide, unsigned int pixelsHigh, void *outputIOSurface) VuoWarnUnusedResult |
Decodes the JSON object js onto a host-provided OpenGL texture's GL_TEXTURE_RECTANGLE_ARB target. | |
bool | VuoImage_resolveInterprocessJsonOntoFramebuffer (struct json_object *js, VuoGlContext context, bool flip, bool stretch) VuoWarnUnusedResult |
Decodes the JSON object js onto the framebuffer of a host-provided OpenGL context. | |
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. | |
#define VuoImage_OVERRIDES_INTERPROCESS_SERIALIZATION |
This type implements _getInterprocessJson()
.
Definition at line 50 of file VuoImage.h.
#define VuoImage_SUPPORTS_COMPARISON |
Instances of this type can be compared and sorted.
Definition at line 49 of file VuoImage.h.
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.
Definition at line 47 of file VuoImage.h.
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).
Definition at line 58 of file VuoImage.h.
enum VuoImageSamplingMode |
Different types of image interpolation.
Definition at line 87 of file VuoImage.h.
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.
Definition at line 772 of file VuoImage.c.
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
.
Definition at line 692 of file VuoImage.c.
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.
Definition at line 64 of file VuoImage.c.
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.
Definition at line 88 of file VuoImageGet.cc.
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. Row-major, starting at the bottom (flipped). No row padding. 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:
|
Definition at line 399 of file VuoImage.c.
VuoImageColorDepth VuoImage_getColorDepth | ( | const VuoImage | image | ) |
Returns the color depth of the image.
Definition at line 860 of file VuoImage.c.
struct json_object * VuoImage_getInterprocessJson | ( | const VuoImage | value | ) |
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.
Definition at line 1505 of file VuoImage.c.
char * VuoImage_getInterprocessString | ( | const VuoImage | value | ) |
Automatically generated function.
struct json_object * VuoImage_getJson | ( | const VuoImage | value | ) |
Encodes value
as a JSON object.
This function may be called from any thread.
Definition at line 1485 of file VuoImage.c.
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.
Definition at line 852 of file VuoImage.c.
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.
Definition at line 1566 of file VuoImage.c.
VuoImageWrapMode VuoImage_getWrapMode | ( | VuoImage | image | ) |
Returns the image's wrap mode.
Definition at line 540 of file VuoImage.c.
bool VuoImage_isBlackOrTransparent | ( | const VuoImage | image, |
const unsigned char | tolerance | ||
) |
Definition at line 823 of file VuoImage.c.
bool VuoImage_isEmpty | ( | const VuoImage | image | ) |
Definition at line 801 of file VuoImage.c.
Returns true if the size of a
is less than the size of b
.
Definition at line 782 of file VuoImage.c.
bool VuoImage_isPopulated | ( | const VuoImage | image | ) |
Definition at line 844 of file VuoImage.c.
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.
Definition at line 154 of file VuoImage.c.
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.
Definition at line 185 of file VuoImage.c.
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.
Definition at line 217 of file VuoImage.c.
VuoImage VuoImage_makeColorImage | ( | VuoColor | color, |
unsigned int | pixelsWide, | ||
unsigned int | pixelsHigh | ||
) |
Makes a solid-color image.
Definition at line 619 of file VuoImage.c.
VuoImage VuoImage_makeCopy | ( | VuoImage | image, |
bool | flip, | ||
unsigned int | forcePixelsWide, | ||
unsigned int | forcePixelsHigh, | ||
bool | forceAlpha | ||
) |
Returns a new texture copy of the passed image.
image | Nay be either GL_TEXTURE_2D or GL_TEXTURE_RECTANGLE_ARB . |
flip | If true, the copied image is flipped upside-down relative to the source image. |
forcePixelsWide | If 0, the output image has the same width as the input image. Otherwise stretches the image. |
forcePixelsHigh | If 0, the output image has the same height as the input image. Otherwise stretches the image. |
forceAlpha | If true, the copied image will have an alpha channel, even if the source image doesn't. |
forcePixelsWide
, forcePixelsHigh
, and forceAlpha
parameters. Definition at line 642 of file VuoImage.c.
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 __fp16 * ; when 32bpc, pixels should be float * . |
freeCallback |
Definition at line 251 of file VuoImage.c.
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
).
Definition at line 259 of file VuoImage.c.
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: Definition at line 931 of file VuoImage.c.
VuoImage VuoImage_makeFromJsonWithDimensions | ( | struct json_object * | js, |
unsigned int | requestedPixelsWide, | ||
unsigned int | requestedPixelsHigh | ||
) |
Decodes the JSON object js
to create a new VuoImage.
If the VuoImage's size matches the provided requestedPixelsWide
x requestedPixelsHigh
, this method behaves the same as VuoImage_makeFromJson. Otherwise, it stretches the image to the requested size.
This function may be called from any thread.
Definition at line 963 of file VuoImage.c.
Copies image
to a new GL_TEXTURE_RECTANGLE_ARB
texture.
GL_TEXTURE_2D
internally. Definition at line 674 of file VuoImage.c.
VuoImage VuoImage_mapColors | ( | VuoImage | image, |
VuoList_VuoColor | colors, | ||
VuoReal | filterOpacity | ||
) |
Returns a color-mapped copy of image.
(Or, if colors is empty, returns image.)
Definition at line 27 of file VuoImageMapColors.c.
void VuoImage_release | ( | VuoImage | value | ) |
Automatically generated function.
bool VuoImage_resolveInterprocessJsonOntoFramebuffer | ( | json_object * | js, |
VuoGlContext | context, | ||
bool | flip, | ||
bool | stretch | ||
) |
Decodes the JSON object js
onto the framebuffer of a host-provided OpenGL context.
js | An interprocess JSON object (from, e.g., VuoRunner::getPublishedOutputPortValue) containing an ioSurface . |
context | A CGLContextObj. This must be part of the same share group as the context passed to VuoGlContext_setGlobalRootContext. |
flip | If true, the image is flipped upside-down when rendering to the framebuffer. |
stretch | How to fit the image to the framebuffer. If false, the image is drawn 1:1 without scaling/stretching, and the edges are clamped. If true, the image is stretched to fit the framebuffer's viewport. |
This function may be called from any thread. (However, the caller is responsible for ensuring that the GL context is not used simultaneously on multiple threads.)
Definition at line 1259 of file VuoImage.c.
bool VuoImage_resolveInterprocessJsonUsingClientTexture | ( | struct json_object * | js, |
GLuint | clientTextureName, | ||
unsigned int | pixelsWide, | ||
unsigned int | pixelsHigh, | ||
void * | outputIOSurface | ||
) |
Decodes the JSON object js
onto a host-provided OpenGL texture's GL_TEXTURE_RECTANGLE_ARB
target.
js | An interprocess JSON object (from, e.g., VuoRunner::getPublishedOutputPortValue) containing an ioSurface . | |
clientTextureName | The OpenGL texture name that the image should be attached to. The host app must not call glTexImage2D() on the texture, since this makes the texture incompatible with the IOSurface backing. | |
pixelsWide | The width of clientTextureName . | |
pixelsHigh | The height of clientTextureName . | |
[out] | outputIOSurface | Upon return, this contains the IOSurfaceRef backing the output texture. When the host app is finished with the output texture, it must signal and release the IOSurfaceRef: VuoIoSurfacePool_signal(outputIOSurface); CFRelease(outputIOSurface);This function may be called from any thread. |
Definition at line 1167 of file VuoImage.c.
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 (from, e.g., VuoRunner::getPublishedOutputPortValue) 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 IOSurfaceRef backing the output texture. When the host app is finished with the output texture, it must signal and release the IOSurfaceRef: VuoIoSurfacePool_signal(outputIOSurface); CFRelease(outputIOSurface);This function may be called from any thread. |
Definition at line 1097 of file VuoImage.c.
void VuoImage_retain | ( | VuoImage | value | ) |
Automatically generated function.
void VuoImage_setSamplingMode | ( | VuoImage | image, |
VuoImageSamplingMode | samplingMode | ||
) |
Changes the image's sampling mode.
Definition at line 596 of file VuoImage.c.
void VuoImage_setWrapMode | ( | VuoImage | image, |
VuoImageWrapMode | wrapMode | ||
) |
Changes the image's wrap mode.
Definition at line 567 of file VuoImage.c.