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;
}| 字段名 | 类型 | 说明 |
|---|---|---|
data | byte[] | 图片像素数据,通常为 RGBA 像素数据 |
width | int | 写入图片的宽度,最大宽度为 4096 |
height | int | 写入图片的高度,最大高度为 4096 |
fileType | String | 写入图片的格式,当前支持 jpg、png |
reverse | boolean | 是否需要将写入的数据按 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 私有缓存目录,避免额外申请外部存储权限。
