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;
}| 字段名 | 类型 | 说明 |
|---|---|---|
data | byte[] | 图片像素数据,通常为 RGBA 像素数据 |
width | int | 图片宽度,最大宽度为 4096 |
height | int | 图片高度,最大高度为 4096 |
fileType | String | 写入图片的格式,目前支持 jpg、png |
reverse | boolean | 是否需要将写入的数据按 Y 轴反转,默认为 false |
返回说明
通过 SUDOPStateHandle 将图片保存结果返回给 SDK。
保存成功
保存成功时调用:
java
handle.success(dataJson);其中 dataJson 为 JSON 字符串,示例:
json
{
"tempFilePath": "/data/user/0/xxx/cache/sud_temp_xxx.png"
}| 字段名 | 类型 | 说明 |
|---|---|---|
tempFilePath | String | 保存成功后的临时图片文件路径 |
errMsg | String | 可选字段,错误或提示信息。成功时通常可不传 |
保存失败
保存失败时调用:
java
handle.failure(retCode, retMsg);| 参数 | 类型 | 说明 |
|---|---|---|
retCode | int | 错误码,0 表示成功,非 0 表示失败 |
retMsg | String | 错误描述信息 |
示例:
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 私有缓存目录,避免额外申请外部存储权限。
