使用ImageEffect编辑图片
=================

#### 场景介绍

ImageEffect提供了一系列接口用于图像的编辑。开发者可以通过ImageEffect接口处理不同图像输入类型Pixelmap、NativeWindow、NativeBuffer或Uri，获得滤镜处理效果。

针对ImageEffect，常见的开发场景如下：

*   通过ImageEffect提供的Native API接口添加滤镜或滤镜链，设置输入图像，最终生效滤镜效果。
*   通过注册自定义滤镜，实现开发者的定制化滤镜效果。
*   通过EffectFilter提供的Native API接口快速实现单个滤镜的处理效果。

#### 接口说明

详细的接口说明请参考[ImageEffect](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-imageeffect)。

#### 开发步骤

**添加动态链接库**

CMakeLists.txt中添加以下lib。

target\_link\_libraries(entry PUBLIC
    libace\_ndk.z.so
    libimage\_effect.so
    libpixelmap.so
    libnative\_window.so
    libnative\_buffer.so
)

根据处理的图像类型添加对应动态链接库：Pixelmap(libpixelmap.so)、NativeWindow(libnative\_window.so)、NativeBuffer(libnative\_buffer.so)

**添加头文件**

#include <hilog/log.h>
#include <multimedia/image\_effect/image\_effect.h>
#include <multimedia/image\_effect/image\_effect\_filter.h>
#include <multimedia/image\_effect/image\_effect\_errors.h>

#### \[h2\]通过ImageEffect提供的接口生效图像效果

1.  创建ImageEffect实例。
    
    // 创建imageEffect实例，“ImageEdit”是imageEffect实例别名。
    OH\_ImageEffect \*imageEffect = OH\_ImageEffect\_Create("ImageEdit");
    
2.  添加EffectFilter滤镜。
    
    // 添加滤镜，获取OH\_EffectFilter实例。多次调用该接口可以添加多个滤镜，组成滤镜链。
    OH\_EffectFilter \*filter = OH\_ImageEffect\_AddFilter(imageEffect, OH\_EFFECT\_BRIGHTNESS\_FILTER);
    if (filter == nullptr) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_AddFilter fail!");
        return;
    }
    // 设置滤镜参数, 例如：滤镜强度设置为50。
    ImageEffect\_Any value = { .dataType = ImageEffect\_DataType::EFFECT\_DATA\_TYPE\_FLOAT, .dataValue.floatValue = 50.f };
    ImageEffect\_ErrorCode errorCode = OH\_EffectFilter\_SetValue(filter, OH\_EFFECT\_FILTER\_INTENSITY\_KEY, &value);
    
3.  设置处理数据。
    
    **场景一：设置OH\_PixelmapNative输入类型。**
    
    OH\_PixelmapNative的具体使用方法请参考[Pixelmap开发指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/image-pixelmap-operation-native)。
    
    // 设置输入的Pixelmap。
    errorCode = OH\_ImageEffect\_SetInputPixelmap(imageEffect, inputPixelmap);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_SetInputPixelmap fail!");
        return;
    }
    
    // 设置输出的Pixelmap（可选），不调用该接口时会在输入Pixelmap上直接生效滤镜效果。
    errorCode = OH\_ImageEffect\_SetOutputPixelmap(imageEffect, outputPixelmap);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_SetOutputPixelmap fail!");
        return;
    }
    
    **场景二：设置OH\_NativeBuffer输入类型。**
    
    OH\_NativeBuffer的具体使用方法请参考[NativeBuffer开发指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/native-buffer-guidelines)。
    
    // 设置输入的NativeBuffer。
    errorCode = OH\_ImageEffect\_SetInputNativeBuffer(imageEffect, inputNativeBuffer);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_SetInputNativeBuffer fail!");
        return;
    }
    
    // 设置输出的NativeBuffer（可选），不调用该接口时会在输入NativeBuffer上直接生效滤镜效果。
    errorCode = OH\_ImageEffect\_SetOutputNativeBuffer(imageEffect, outputNativeBuffer);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_SetOutputNativeBuffer fail!");
        return;
    }
    
    **场景三：设置URI输入类型。**
    
    // 设置输入的URI。
    errorCode = OH\_ImageEffect\_SetInputUri(imageEffect, inputUri);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_SetInputUri fail!");
        return;
    }
    // 设置输出的URI（可选），不调用该接口时会在输入URI上直接生效滤镜效果。
    errorCode = OH\_ImageEffect\_SetOutputUri(imageEffect, outputUri);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_SetOutputUri fail!");
        return;
    }
    
    **场景四：设置纹理输入类型。**
    
    纹理输入场景是使用硬件GPU渲染的高性能场景，此场景下，应用需要提供合法的OpenGL上下文环境，并在正确的环境下，设置参数以及进行渲染操作。
    
    // 设置输入的纹理ID。
    errorCode = OH\_ImageEffect\_SetInputTextureId(imageEffect, inputTex, ColorSpaceName::SRGB);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_SetInputTextureId fail!");
        return;
    }
    
    // 设置输出的纹理ID, 注意不能与输入是同一块纹理，否则可能产生渲染异常。
    errorCode = OH\_ImageEffect\_SetOutputTextureId(imageEffect, outputTex);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_SetOutputTextureId fail!");
        return;
    }
    
    **场景五：设置OHNativeWindow输入类型。**
    
    以相机预览场景为例来说明OHNativeWindow输入场景。XComponent组件为相机预览流提供的SurfaceId，可在native c++层将SurfaceId转换成OHNativeWindow，下面提供一份代码示例。
    
    XComponent模块的具体使用方法请参考[XComponent组件参考](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-xcomponent)。
    
    NativeWindow模块的具体使用方法请参考[OHNativeWindow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-nativewindow)。
    
    Camera的具体使用方法请参考[Camera预览参考](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/native-camera-preview)。
    
    (1) 在xxx.ets中添加一个XComponent组件。
    
    XComponent({
       id: 'xcomponentId',
       type: 'surface',
       controller: this.mXComponentController,
       libraryname: 'entry'
    })
    .onLoad(() => {
       // 获取XComponent的SurfaceId。
       this.mSurfaceId = this.mXComponentController.getXComponentSurfaceId()
    
       // 调用native接口获取输入SurfaceId。
       this.mSurfaceId = imageEffect.getSurfaceId(this.mSurfaceId)
    
       // 调用相机接口启动预览，将获取到的输入SurfaceId传递给相机框架。
       // ...
    })
    .width('100%')
    .height('100%')
    
    (2) imageEffect.getSurfaceId的native c++层具体实现。
    
    // 根据SurfaceId创建NativeWindow，注意创建出来的NativeWindow在使用结束后需要主动调用OH\_NativeWindow\_DestroyNativeWindow进行释放。
    uint64\_t outputSurfaceId;
    std::istrstream iss(outputSurfaceIdStr);
    iss >> outputSurfaceId;
    OHNativeWindow \*outputNativeWindow = nullptr;
    int32\_t res = OH\_NativeWindow\_CreateNativeWindowFromSurfaceId(outputSurfaceId, &outputNativeWindow);
    if (res != 0) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_NativeWindow\_CreateNativeWindowFromSurfaceId fail!");
        return;
    }
    
    // 设置输出显示的Surface。
    ImageEffect\_ErrorCode errorCode = OH\_ImageEffect\_SetOutputSurface(imageEffect, outputNativeWindow);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_SetOutputSurface fail!");
        return;
    }
    // 获取输入的Surface。注意获取的inputNativeWindow在使用结束后需要主动调用OH\_NativeWindow\_DestroyNativeWindow进行释放。
    OHNativeWindow \*inputNativeWindow = nullptr;
    errorCode = OH\_ImageEffect\_GetInputSurface(imageEffect, &inputNativeWindow);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_GetInputSurface fail!");
        return;
    }
    
    // 从获取到输入的NativeWindow中获取SurfaceId。
    uint64\_t inputSurfaceId = 0;
    res = OH\_NativeWindow\_GetSurfaceId(inputNativeWindow, &inputSurfaceId);
    if (res != 0) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_NativeWindow\_GetSurfaceId fail!");
        return;
    }
    
    // 将SurfaceId转成字符串进行返回。
    std::string inputSurfaceIdStr = std::to\_string(inputSurfaceId);
    
4.  启动效果器。
    
    // 执行生效滤镜效果。
    errorCode = OH\_ImageEffect\_Start(imageEffect);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_Start fail!");
        return;
    }
    
5.  停止生效效果（可选，仅在输入Surface场景下才有效）。
    
    // 停止生效滤镜效果。
    errorCode = OH\_ImageEffect\_Stop(imageEffect);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_Stop fail!");
        return;
    }
    
6.  序列化效果器（可选）。
    
    char \*info = nullptr;
    errorCode = OH\_ImageEffect\_Save(imageEffect, &info);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_Save fail!");
        return;
    }
    
7.  销毁效果器实例。
    
    // 释放imageEffect实例资源。
    errorCode = OH\_ImageEffect\_Release(imageEffect);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_ImageEffect\_Release fail!");
        return;
    }
    

#### \[h2\]自定义滤镜

以下步骤描述了如何实现并注册自定义滤镜接口：

1.  定义 ImageEffect\_FilterDelegate。
    
    // 图像信息结构体。
    struct EffectBufferInfo {
        void \*addr = nullptr;
        int32\_t width = 0;
        int32\_t height = 0;
        int32\_t rowSize = 0;
        ImageEffect\_Format format = ImageEffect\_Format::EFFECT\_PIXEL\_FORMAT\_UNKNOWN;
    };
    
    // 自定义滤镜具体实现。
    ImageEffect\_FilterDelegate filterDelegate = {
        .setValue = \[\](OH\_EffectFilter \*filter, const char \*key, const ImageEffect\_Any \*value) {
            // 参数校验，校验成功时返回true，否则返回false。
            // ...
            return true;
        },
        .render = \[\](OH\_EffectFilter \*filter, OH\_EffectBufferInfo \*info, OH\_EffectFilterDelegate\_PushData pushData) {
            return Render(filter, info, pushData);
        },
        .save = \[\](OH\_EffectFilter \*filter, char \*\*info) {
            // 获取自定义所设置的滤镜参数，其中"Brightness"为自定义滤镜的Key，由开发者自己任意指定。
            ImageEffect\_Any value;
            ImageEffect\_ErrorCode errorCode = OH\_EffectFilter\_GetValue(filter, "Brightness", &value);
            if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
            OH\_LOG\_ERROR(LOG\_APP, "OH\_EffectFilter\_GetValue fail!");
            return false;
            }
             
            // 生成键值对信息。
            json values;
            values\["Brightness"\] = value.dataValue.floatValue;
            json root;
            root\["name"\] = "CustomBrightness";
            root\["values"\] = values;
    
            // 将json对象转成字符串infoStr。
            // ...
    
            // 对\*info赋值序列化字符串地址。
            \*info = infoStr;
            return true;
        },
        .restore = \[\](const char \*info) {
            // 创建OH\_EffectFilter实例，其中"CustomBrightness"为自定义滤镜的滤镜名。
            OH\_EffectFilter \*filter = OH\_EffectFilter\_Create("CustomBrightness");
            // 解析json字符串info获取key和value。
            // ...
    
            // 设置滤镜参数, value为info中按json解析出来的参数。
            ImageEffect\_ErrorCode errorCode = OH\_EffectFilter\_SetValue(filter, "Brightness", &value);
    
            // ...
            return filter;
        }
    };
    
    其中Render接口的实现分两种场景。
    
    **场景一：自定义算法可以直接修改info中的像素数据（比如：亮度调节滤镜）。**
    
    bool Render(OH\_EffectFilter \*filter, OH\_EffectBufferInfo \*info, OH\_EffectFilterDelegate\_PushData pushData)
    {
        // 获取图像信息具体参数。
        EffectBufferInfo inputBufferInfo;
        OH\_EffectBufferInfo\_GetAddr(info, &inputBufferInfo.addr);
        OH\_EffectBufferInfo\_GetWidth(info, &inputBufferInfo.width);
        OH\_EffectBufferInfo\_GetHeight(info, &inputBufferInfo.height);
        OH\_EffectBufferInfo\_GetRowSize(info, &inputBufferInfo.rowSize);
        OH\_EffectBufferInfo\_GetEffectFormat(info, &inputBufferInfo.format);
    
        // 调用自定义滤镜算法。
        ApplyCustomAlgo(inputBufferInfo);
    
        // 编辑完成后调用pushData直接传递原图。
        pushData(filter, info);
        return true;
    }
    
    **场景二：自定义算法不能直接修改info中的像素数据（比如：裁剪滤镜）。**
    
    bool Render(OH\_EffectFilter \*filter, OH\_EffectBufferInfo \*info, OH\_EffectFilterDelegate\_PushData pushData)
    {
        // 获取图像信息具体参数。
        EffectBufferInfo inputBufferInfo;
        OH\_EffectBufferInfo\_GetAddr(info, &inputBufferInfo.addr);
        OH\_EffectBufferInfo\_GetWidth(info, &inputBufferInfo.width);
        OH\_EffectBufferInfo\_GetHeight(info, &inputBufferInfo.height);
        OH\_EffectBufferInfo\_GetRowSize(info, &inputBufferInfo.rowSize);
        OH\_EffectBufferInfo\_GetEffectFormat(info, &inputBufferInfo.format);
    
        // 创建输出像素信息。
        EffectBufferInfo outputBufferInfo = CreateOutputBufferInfo(inputBufferInfo);
    
        // 调用自定义滤镜算法。
        ApplyCustomAlgo(inputBufferInfo, outputBufferInfo);
    
        // 生成outputOhInfo。
        OH\_EffectBufferInfo \*outputOhInfo = OH\_EffectBufferInfo\_Create();
        OH\_EffectBufferInfo\_SetAddr(outputOhInfo, outputBufferInfo.addr);
        OH\_EffectBufferInfo\_SetWidth(outputOhInfo, outputBufferInfo.width);
        OH\_EffectBufferInfo\_SetHeight(outputOhInfo, outputBufferInfo.height);
        OH\_EffectBufferInfo\_SetRowSize(outputOhInfo, outputBufferInfo.rowSize);
        OH\_EffectBufferInfo\_SetEffectFormat(outputOhInfo, outputBufferInfo.format);
    
        // 编辑完成后调用pushData传递outputOhInfo。
        pushData(filter, outputOhInfo);
    
        // 释放资源。
        OH\_EffectBufferInfo\_Release(outputOhInfo);
        ReleaseOutputBuffer(outputBufferInfo.addr);
    
        return true;
    }
    
2.  生成自定义滤镜信息。
    
    // 创建OH\_EffectFilterInfo实例。
    OH\_EffectFilterInfo \*customFilterInfo = OH\_EffectFilterInfo\_Create();
    if (customFilterInfo ==nullptr) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_EffectFilter\_GetValue fail!");
        return;
    }
    
    // 设置自定义滤镜滤镜名。
    OH\_EffectFilterInfo\_SetFilterName(customFilterInfo, "CustomBrightness");
    
    // 设置自定义滤镜所支持的内存类型。
    ImageEffect\_BufferType bufferTypeArray\[\] = { ImageEffect\_BufferType::EFFECT\_BUFFER\_TYPE\_PIXEL };
    OH\_EffectFilterInfo\_SetSupportedBufferTypes(customFilterInfo, sizeof(bufferTypeArray) / sizeof(ImageEffect\_BufferType), bufferTypeArray);
    
    // 设置自定义滤镜所支持的像素格式。
    ImageEffect\_Format formatArray\[\] = { ImageEffect\_Format::EFFECT\_PIXEL\_FORMAT\_RGBA8888 };
    OH\_EffectFilterInfo\_SetSupportedFormats(customFilterInfo, sizeof(formatArray) / sizeof(ImageEffect\_Format), formatArray);
    
3.  将 ImageEffect\_FilterDelegate 注册到效果器。
    
    // 注册自定义滤镜。
    ImageEffect\_ErrorCode errorCode = OH\_EffectFilter\_Register(customFilterInfo, &filterDelegate);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_EffectFilter\_Register fail!");
        return;
    }
    

#### \[h2\]EffectFilter快速实现单个滤镜的处理效果

1.  创建滤镜。
    
    // 创建滤镜。比如：创建对比度效果器。
    OH\_EffectFilter \*filter = OH\_EffectFilter\_Create(OH\_EFFECT\_CONTRAST\_FILTER);
    
2.  设置滤镜参数。
    
    // 设置滤镜参数, 滤镜强度设置为50。
    ImageEffect\_Any value = {.dataType = ImageEffect\_DataType::EFFECT\_DATA\_TYPE\_FLOAT, .dataValue.floatValue = 50.f};
    ImageEffect\_ErrorCode errorCode = OH\_EffectFilter\_SetValue(filter, OH\_EFFECT\_FILTER\_INTENSITY\_KEY, &value);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_EffectFilter\_SetValue fail!");
        return;
    }
    
3.  生效滤镜。
    
    // 生效滤镜效果。
    errorCode = OH\_EffectFilter\_Render(filter, inputPixelmap, outputPixelmap);
    
4.  销毁滤镜实例。
    
    // 销毁滤镜实例。
    errorCode = OH\_EffectFilter\_Release(filter);
    

#### \[h2\]查询能力

*   根据滤镜名查询滤镜信息。
    
    // 创建OH\_EffectFilterInfo实例。
    OH\_EffectFilterInfo \*filterInfo = OH\_EffectFilterInfo\_Create();
    if (filterInfo == nullptr) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_EffectFilterInfo\_Create fail!");
        return;
    }
    
    // 根据滤镜名查询滤镜能力信息。
    ImageEffect\_ErrorCode errorCode = OH\_EffectFilter\_LookupFilterInfo(OH\_EFFECT\_BRIGHTNESS\_FILTER, filterInfo);
    if (errorCode != ImageEffect\_ErrorCode::EFFECT\_SUCCESS) {
        OH\_LOG\_ERROR(LOG\_APP, "OH\_EffectFilter\_LookupFilterInfo fail!");
        return;
    }
    
    // 从滤镜能力信息中获取滤镜名。
    char \*name = nullptr;
    OH\_EffectFilterInfo\_GetFilterName(filterInfo, &name);
    
    // 获取支持的内存类型。
    uint32\_t supportedBufferTypesCnt = 0;
    ImageEffect\_BufferType \*bufferTypeArray = nullptr;
    OH\_EffectFilterInfo\_GetSupportedBufferTypes(filterInfo, &supportedBufferTypesCnt, &bufferTypeArray);
    
    // 获取支持的像素类型信息。
    uint32\_t supportedFormatsCnt = 0;
    ImageEffect\_Format \*formatArray = nullptr;
    OH\_EffectFilterInfo\_GetSupportedFormats(filterInfo, &supportedFormatsCnt, &formatArray);
    
    // 销毁OH\_EffectFilterInfo实例。
    OH\_EffectFilterInfo\_Release(filterInfo);
    
*   根据条件查询满足条件的滤镜。
    
    // 查询所有的Filter，需要主动进行资源释放。
    ImageEffect\_FilterNames \*filterNames = OH\_EffectFilter\_LookupFilters("Default");
    
    // ...
    
    // 释放FilterNames虚拟内存资源。
    OH\_EffectFilter\_ReleaseFilterNames();