Skip to content

saveImageTemp ​

保存图片到临时文件 ​

该方法用于将 SDK 传入的图片像素数据保存为 APP 本地临时图片文件。通常用于游戏截图、分享图片、二维码图片、战绩图等场景。

APP 侧需要根据传入的像素数据、图片宽高、图片格式等参数生成临时图片文件,并通过 handle.success(resultJson) 将临时文件路径返回给 SDK。


方法声明 ​

java
/**
 * 保存图片到临时文件
 *
 * @param handle 用于向 SDK 返回处理结果的状态句柄。
 *               成功返回时数据示例:{"tempFilePath":"filePath","errMsg":"msg"}
 * @param params 请求参数
 */
void saveImageTemp(SUDOPStateHandle handle, SUDOPSaveImageTempParams params);

参数说明 ​

SUDOPSaveImageTempParams ​

java
public class SUDOPSaveImageTempParams {
    /**
     * 像素数据
     */
    public byte[] data;

    /**
     * 写入图片的宽度,最大宽度为 4096
     */
    public int width;

    /**
     * 写入图片的高度,最大高度为 4096
     */
    public int height;

    /**
     * 写入图片的格式,支持的类型为 jpg、png
     */
    public String fileType;

    /**
     * 是否需要将写入的数据按 y 轴反转,默认为 false
     */
    public boolean reverse;
}
字段名类型说明
databyte[]图片像素数据,通常为 RGBA 像素数据
widthint图片宽度,最大宽度为 4096
heightint图片高度,最大高度为 4096
fileTypeString写入图片的格式,目前支持 jpg、png
reverseboolean是否需要将写入的数据按 Y 轴反转,默认为 false

返回说明 ​

通过 SUDOPStateHandle 将图片保存结果返回给 SDK。

保存成功 ​

保存成功时调用:

java
handle.success(dataJson);

其中 dataJson 为 JSON 字符串,示例:

json
{
  "tempFilePath": "/data/user/0/xxx/cache/sud_temp_xxx.png"
}
字段名类型说明
tempFilePathString保存成功后的临时图片文件路径
errMsgString可选字段,错误或提示信息。成功时通常可不传

保存失败 ​

保存失败时调用:

java
handle.failure(retCode, retMsg);
参数类型说明
retCodeint错误码,0 表示成功,非 0 表示失败
retMsgString错误描述信息

示例:

java
handle.failure(-1, "This file type is not supported:webp");

运行行为 ​

  • 由 SDK 触发:当 SDK 需要将图片像素数据保存为临时文件时,会调用 saveImageTemp。
  • APP 负责文件生成:APP 侧需要根据 params.data、params.width、params.height 和 params.fileType 生成本地临时图片文件。
  • 支持异步处理:图片编码和文件写入可能比较耗时,建议在子线程中处理,避免阻塞主线程。
  • 结果回传:保存完成后,通过 handle.success(...) 返回临时文件路径;如果保存失败,则通过 handle.failure(...) 返回错误信息。
  • 临时文件生命周期:该接口保存的是临时图片文件,APP 可根据自身缓存策略在合适时机清理。

代码示例 ​

java
@Override
public void saveImageTemp(SUDOPStateHandle handle, SUDOPSaveImageTempParams params) {
    new Thread() {
        @Override
        public void run() {
            super.run();

            String filePath = getTempFile(params.fileType);

            try {
                if ("jpg".equals(params.fileType)) {
                    QgClientUtils.rgbaToJpeg(
                            params.data,
                            params.width,
                            params.height,
                            filePath
                    );
                } else if ("png".equals(params.fileType)) {
                    QgClientUtils.rgbaToPng(
                            params.data,
                            params.width,
                            params.height,
                            filePath
                    );
                } else {
                    handle.failure(
                            -1,
                            "This file type is not supported:" + params.fileType
                    );
                    return;
                }
            } catch (IOException e) {
                handle.failure(-1, "error:" + e);
                return;
            }

            JSONObject obj = new JSONObject();
            try {
                obj.put("tempFilePath", filePath);
            } catch (Exception e) {
                e.printStackTrace();
            }

            String result = obj.toString();
            handle.success(result);
        }
    }.start();
}

推荐实现流程 ​

text
SDK 调用 saveImageTemp
        ↓
APP 校验参数 data / width / height / fileType
        ↓
APP 创建临时文件路径
        ↓
根据 fileType 将 RGBA 像素数据编码为 jpg 或 png
        ↓
写入本地临时文件
        ↓
写入成功:handle.success({"tempFilePath":"..."})
写入失败:handle.failure(retCode, retMsg)

注意事项 ​

  • 必须回调:无论保存成功还是失败,都需要调用 handle.success(...) 或 handle.failure(...)。
  • 建议异步处理:图片编码和磁盘写入可能耗时,建议放在子线程中执行,避免阻塞 UI 线程。
  • 文件格式限制:当前仅支持 jpg 和 png,不支持的格式需要返回失败。
  • 图片尺寸限制:width 最大为 4096,height 最大为 4096,超出限制时建议返回失败。
  • 数据完整性:保存前建议校验 params.data 是否为空,以及数据长度是否与 width * height 对应的像素格式匹配。
  • Y 轴反转:如果 params.reverse 为 true,APP 侧应在写入图片前按 Y 轴反转像素数据。
  • 临时文件清理:返回的 tempFilePath 为临时文件路径,APP 可在分享完成、上传完成或缓存过期后清理。
  • 权限处理:建议优先保存到 APP 私有缓存目录,避免额外申请外部存储权限。