CoronaGraphics.h

类型 C 头文件
修订 版本 2024.3703
关键词 iOS, Solar2D Native, C, CoronaGraphics.h
另请参阅 Corona C 函数
TextureResourceExternal

概述

CoronaGraphics.h 包含与 Corona 图形流水线交互的接口。这些接口都以 CoronaExternal 为前缀。

外部位图

这些接口允许从 C 插件加载的位图通过将它们作为 TextureResourceExternal 对象推送到 Lua 中来在 Corona 中显示。包装在 Lua TextureResourceExternal 对象中的位图可以通过接受图像 filename 和 baseDir 参数的 API 在 Corona 中显示，例如 Lua display.newImage()、display.newImageRect() 和 graphics.newImageSheet() 函数。纹理也可以应用于具有 fill 属性的显示对象，例如 ShapeObject。

请参阅《纹理加载/管理》指南，了解如何在 Corona 中使用和管理纹理的示例。

函数

CoronaExternalPushTexture()

CoronaExternalGetUserData()

CoronaExternalFormatBPP()

枚举

CoronaExternalBitmapFormat

结构体

CoronaExternalTextureCallbacks

示例

此示例是一个假设的 plugin.texturer，它具有一个函数 newTexture()，该函数将图像从第三方API（以 TPA_ 为前缀）推送。图像具有索引，并且第三方API 可以使用这些索引检索图像。

  1. 使用 luaopen_ 函数声明插件。这对于所有插件都是通用的。
CORONA_EXPORT int luaopen_plugin_texturer( lua_State *L )
{
    // Functions in library
    const luaL_Reg kVTable[] =
    {
        { "newTexture", newTexture },
        { NULL, NULL }
    };

    luaL_openlib( L, kName, kVTable, 0 );

    return 1;
}
  1. 实现将推送图像的 newTexture() 函数
/** TextureResourceExternal texturer.newTexture(image) */
int newTexture(lua_State* luaStatePointer)
{
    int image = 0;
    if (lua_type(luaStatePointer, 1) == LUA_TNUMBER)
    {
        image = (int)lua_tointeger(luaStatePointer, 1);
    }
    else
    {
        luaL_argerror( L, 1, "image must be a number")
    }

    // creating callbacks structure and initializing it with zeros
    CoronaExternalTextureCallbacks callbacks = {0};
    // setting size
    callbacks.size = sizeof(CoronaExternalTextureCallbacks);
    // setting callbacks
    callbacks.getWidth = getWidth;
    callbacks.getHeight = getHeight;
    callbacks.onRequestBitmap = onRequestBitmap;
    callbacks.onReleaseBitmap = onReleaseBitmap;
    callbacks.onFinalize = onFinalize;

    // Creating helper structure
    HelperStruct* helper = new HelperStruct();
    helper->image = image;    
    helper->w = TPA_GetImageWidth(image);   //caching width and height
    helper->h = TPA_GetImageHeight(image);

    int ret = CoronaExternalPushTexture(L, &callbacks, (image));

    // Note that we're not deleting `helper` when everything is OK. It would be released in finalizing callback.
    if (ret == 0)
    {
        // something went wrong. Texture was not pushed, so should clean up to prevent memory leak
        delete helper;
    }
    return ret;
}
  1. 实现回调和辅助程序
struct HelperStruct
{
    unsigned w;
    unsigned h;
    int image;
    void *buff;    
}


unsigned getWidth(void* userData)
{
    HelperStruct* self = (HelperStruct*)userData;
    return self->w;
}

unsigned getHeight(void* userData)
{
    HelperStruct* self = (HelperStruct*)userData;
    return self->h;
}

const void* onRequestBitmap(void* userData)
{
    HelperStruct* self = (HelperStruct*)userData;

    int sz = self->w*self->h*4; // we know that our API always return 4 byte RGBA
    self->buff = new unsigned char[sz];
    TPA_GetImageRGBA(self->image, self->buff, sz);
    return self->buff;
}

void onReleaseBitmap(void* userData)
{
    HelperStruct* self = (HelperStruct*)userData;
    delete [] self->buff;
}

void onFinalize(void *userData)
{
    HelperStruct* self = (HelperStruct*)userData;
    // release helper when texture is no longer required
    delete self;
}
  1. 在 Lua 代码中使用插件
local texturer = require( "plugin.texturer" )

local tex = texturer.newTexture( 42 )
display.newImageRect( tex.filename, tex.baseDir, tex.width, tex.height )
tex:releaseSelf()
注意

创建纹理时，不会立即调用回调。Corona 在帧之间以及仅在需要时创建纹理。此外，在调用 texture:releaseSelf() 之后，texture 不一定会被释放——只有这个 Lua **引用**会被释放。如果有任何显示对象正在使用该纹理，则它不会被释放，以便它们仍然可以正确渲染。