Skip to content

saveImageTempSync ​

同步保存图片到临时文件 ​

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

与 saveImageTemp 不同,saveImageTempSync 不通过 SUDOPStateHandle 异步回调结果,而是直接通过方法返回值返回临时文件路径。


方法声明 ​

java
/**
 * 同步保存图片到临时文件
 *
 * @param params 请求参数
 * @return 保存成功时返回临时图片文件路径;保存失败时返回 null
 */
String saveImageTempSync(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

返回说明 ​

该方法直接通过返回值返回保存结果。

保存成功 ​

返回临时图片文件路径:

java
return filePath;

示例:

text
/data/user/0/com.xxx.xxx/cache/sud_temp_123456.png

保存失败 ​

返回 null:

java
return null;

常见失败场景包括:

  • fileType 不是 jpg 或 png
  • 图片像素数据为空或异常
  • 图片宽高非法
  • 文件创建失败
  • 图片编码失败
  • 文件写入过程中发生 IOException

运行行为 ​

  • 同步执行:调用该方法后,会在当前线程中完成图片编码和文件写入。
  • APP 负责文件生成:APP 侧需要根据 params.data、params.width、params.height、params.fileType 创建临时图片文件。
  • 直接返回结果:保存成功时返回临时文件路径,保存失败时返回 null。
  • 无异步回调:该方法不使用 SUDOPStateHandle,不需要调用 handle.success 或 handle.failure。
  • 临时文件生命周期:返回的文件路径为临时文件,APP 可根据自身缓存策略在合适时机清理。

代码示例 ​

java
@Override
public String saveImageTempSync(SUDOPSaveImageTempParams params) {
    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 {
            return null;
        }
    } catch (IOException e) {
        return null;
    }

    return filePath;
}

推荐实现流程 ​

text
SDK 调用 saveImageTempSync
        ↓
APP 校验 params 参数
        ↓
创建临时文件路径
        ↓
判断 fileType
        ↓
jpg:将 RGBA 数据编码为 JPEG 文件
png:将 RGBA 数据编码为 PNG 文件
其他格式:返回 null
        ↓
写入成功:返回 tempFilePath
写入失败:返回 null

注意事项 ​

  • 同步耗时:该方法会在当前线程执行图片编码和磁盘写入,可能存在耗时操作。若调用发生在主线程,可能造成卡顿。
  • 建议控制图片尺寸:width 和 height 最大建议不超过 4096,避免内存占用过高或编码失败。
  • 仅支持指定格式:当前仅支持 jpg 和 png,不支持的格式应返回 null。
  • 失败返回 null:该接口没有错误码和错误信息,保存失败时统一返回 null。
  • 数据完整性校验:建议保存前检查 params.data 是否为空,以及数据长度是否与图片宽高匹配。
  • Y 轴反转处理:如果 params.reverse 为 true,APP 侧应在写入图片前按 Y 轴反转像素数据。
  • 文件路径有效性:返回的路径应为 APP 可读的本地临时文件路径。
  • 临时文件清理:APP 应根据业务需要清理临时文件,避免缓存占用过多存储空间。
  • 权限建议:建议将图片保存到 APP 私有缓存目录,避免额外申请外部存储权限。