CoronaExternalTextureCallbacks

Revision Release 2022.3683
Keywords iOS, Solar2D Native, C, CoronaGraphics.h, CoronaExternalTextureCallbacks
See also CoronaGraphics.h
Corona C Functions

Overview

This structure contains fields which provide information about the texture and callbacks to be invoked by Corona when events occur or when Corona is requesting information about the texture. Textures are managed by Corona and plugins have no control on when the texture is to be released. Thus, information about a texture's bitmap must be available upon request.

Note

Always initialize an instance of this structure with zeros. Some of the fields are optional and the texture can be created even if they are NULL. Other fields are required, however, and the texture will not be pushed if they aren't present.

CoronaExternalTextureCallbacks callbacks;
memset(&callbacks, 0, sizeof(CoronaExternalTextureCallbacks));
callbacks.size = sizeof(CoronaExternalTextureCallbacks);

Syntax

typedef struct CoronaExternalTextureCallbacks
{
    unsigned long size;
    unsigned int (*getWidth)(void* userData);
    unsigned int (*getHeight)(void* userData);
    const void* (*onRequestBitmap)(void* userData);
    void (*onReleaseBitmap)(void* userData);
    CoronaExternalBitmapFormat (*getFormat)(void* userData);
    void (*onFinalize)(void *userData);
    int (*onGetField)(lua_State *L, const char *field, void* userData);
} CoronaExternalTextureCallbacks;
size (required)

When creating an instance of this type, set this member to the number of bytes the CoronaExternalTextureCallbacks type is. This field is used for identifying the API version.

size = sizeof(CoronaExternalTextureCallbacks);
getWidth (required)

Callback that will be invoked when Corona is requesting the plugin to provide the bitmap's pixel width. This callback receives the userData pointer passed when the texture resource was created. Note that some bitmap formats, such as 8-bit masks, require the width to be a multiple of 4 bytes.

getHeight (required)

Callback that will be invoked when Corona is requesting the plugin to provide the bitmap's pixel height. This callback receives the userData pointer passed when the texture resource was created.

onRequestBitmap (required)

Callback that will be invoked by Corona when the bitmap's pixel array has been requested by Corona's rendering system. This function call will always be followed by a call to the onReleaseBitmap callback. This callback receives the userData pointer passed when the texture resource was created.

Notes

  • This function must return a valid pointer to the data containing bitmap information. Corona expects bitmap data to be a row-by-row array of pixels starting from the top left of the image, and each pixel is represented by bpp = CoronaExternalFormatBPP(getFormat()) bytes. Each color channel uses 1 byte and is ordered the same as the format name, left to right. So, with RGBA format, the R index is 0.

  • The overall size of memory must be at least...

unsigned int bitmapSizeInBytes = getWidth() * getHeight() * bytesPerPixel;
  • Accessing the left-most value of the bitmap (R in RGBA) could be written as...
void* byteArray = onRequestBitmap();
int bytesPerPixel = CoronaExternalFormatBPP(getFormat());
int red = (int)byteArray[((Y * getWidth()) + X) * bytesPerPixel];
  • Remember that the default format, RGBA, uses premultiplied alpha.
onReleaseBitmap (optional)

Callback that will be invoked by Corona to notify the plugin that the texture bitmap's data is no longer required, meaning that the plugin can delete the bitmap data from memory. After this callback is invoked, the pointer previously returned by the onRequestBitmap callback is no longer expected to be valid. This callback receives the userData pointer passed when the texture resource was created.

getFormat (optional)

Callback that will be invoked by Corona when requesting the pixel format of the bitmap. This callback receives the userData pointer passed when the texture resource was created. This must return a CoronaExternalBitmapFormat enum constant, such as kExternalBitmapFormat_RGBA.

onFinalize (optional)

Callback that will be invoked by Corona to notify the plugin that the Lua TextureResourceExternal object is about to be destroyed. After this callback is invoked, no callbacks or returned bitmap pointers can be accessed. Essentially, this releases all objects and resources associated with this texture resource. This callback receives the userData pointer passed when the texture resource was created.

onGetField (optional)

Callback to be invoked when an unknown Lua property has been accessed from the Lua TextureResourceExternal object. This is the plugin's opportunity to provide custom read-only fields from the Lua object. Argument field provides the name of the property being accessed from the TextureResourceExternal object. Argument userData is the pointer passed when the texture resource was created. This function returns the number of values pushed onto the Lua stack.