Update guidance document

README.md

-**RoiEncodeUnit 介绍**
+# **RoiEncodeUnit 介绍**
 
-1. 1、概述
+## **1、概述**
 
-RoiEncodeUnit是ROI编码能力开放接口，三方可通过RoiEncode实现ROI编码功能，通过ROI编码功能控制视频重点关注区域的码率分配情况，提升重点关注区域的视频质量，弱化背景信息，提升视频整体感官。
\ No newline at end of file
+> RoiEncodeUnit是ROI编码能力开放接口，三方可通过RoiEncode实现ROI编码功能，通过ROI编码功能控制视频重点关注区域的码率分配情况，提升重点关注区域的视频质量，弱化背景信息，提升视频整体感官。
+
+## **支持设备**
+
+|      |                                                              |
+| ---- | ------------------------------------------------------------ |
+| 小米 | 小米12S, 小米12S pro，小米12S Ultra，Android T及以上版本的高通平台 |
+| OPPO | Android T及以上版本的高通平台                                |
+| VIVO | Android T及以上版本的高通平台                                |
+
+## **3、工作原理**
+
+## **3.1 架构简介**
+
+![image-20220811153644593](D:\Users\80349658\AppData\Roaming\Typora\typora-user-images\image-20220811153644593.png)
+
+### **3.2 应用层**
+
+基于ROI编码能力而开发的用户应用程序。
+
+### **3.3 API接口层**
+
+提供ROI编码能力开放的具体功能和三方交互的接口，通过此接口接入ROI编码开放能力。
+
+### **3.4 SDK实现层**
+
+主要是对ROI编码进行一层封装，实现 ROI编码能力开放。
+
+# **接入指南**
+
+## **1、开发流程**
+
+RoiencodeClient功能包括初始化、获取版本号、判断RoiEncode是否支持、打开RoiEncode功能、设置RoiEncode参数、获取RoiEncode状态
+
+- 初始化：创建RoiencodeClient所需资源以及进行鉴权等操作。
+
+- 取版本号：获取当前版本号
+
+- 取RoiEncode能力支持状态：获取当前平台是否支持RoiEncode能力
+
+- 打开RoiEncode功能：编码前打开RoiEncode功能
+
+- 设置RoiEncode参数：编码过程中对每一帧设置RoiEncode参数
+
+- 取RoiEncode运行状态：RoiEncode功能是否正常生效
+
+## **2、环境配置**
+
+### **2.1 环境准备**
+
+涉及AS版本/手机版本
+
+### **2.2 配置build.gradle**
+
+### **2.2.1. 修改项目的build.gradle文件**
+
+```
+allprojects {**
+
+**repositories {**
+
+**...**
+
+**maven {**
+
+**url "https://nexus.itgsa.com:5566/repository/gsai-snapshot/"---正式版本修改**
+
+**credentials {**
+
+**username "admin"**
+
+**password "admin123"**
+
+**}**
+
+**}**
+
+**}**
+
+**}
+```
+
+
+
+### **2.2.2. 修改Module的build.gradle文件**
+
+修改具体使用到RoiEncodeUnit的Module的build.gradle，进行如下配置：
+
+```
+**dependencies {**
+
+**implementation ‘gsai.sdk:roiencode-client:1.0.0'**
+
+**}
+```
+
+
+
+### **2.3 初始化RoiEncodeUnit**
+
+该初始化代码包含了鉴权功能，鉴权是异步的，建议尽可能早的去进行初始化（推荐放到Application的onCreate的里面去执行），防止在使用具体功能时，未初始化完成  
+后续所有动作都需要等鉴权成功后才能执行  
+可以通过该接口的返回值判断是否支持RoiencodeClient，如果该接口返回值为null则表示该机型不支持。
+
+```
+import com.itgsa.opensdk.roiencode.RoiencodeClient;**
+
+**Context mContext = getApplicationContext();**
+
+**RoiencodeClient mRoiEncodeUnit = RoiencodeClient.initialize(mContext);
+```
+
+
+
+# **接口指导**
+
+## **1、接口说明**
+
+| 接口                                                         | 说明                                                         |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| int getVersion()                                             | 返回值：参数类型：int参数说明: 获取SDK版本号初始版本号：10000表示1.0.0 |
+| int isRoiEncodeSupported(MediaCodec encoder)                 | 返回值：参数类型：int参数说明: 是否支持RoiEncode能力参数取值：1---支持RoiEncode     0---不支持RoiEncode |
+| int enableRoiEncode(MediaFormat mediaFromat,            Int enableRoiEncode) | 入参:参数名：enableRoiEncode参数类型：int参数说明： 开/关ROI编码能力参数取值范围：1/0 参数名：mediaFormat参数类型：MediaFormat 参数说明： 编码参数 返回值：参数类型：int参数说明: 入参是否满足条件参数取值：  0---入参满足条件  -10001--当前编码类型不支持该能力-10002--当前bitratemode不支持该能力-10003--入参enableRoiEnable取值异常 |
+| int setRoiParameter(MediaCodec encoder,           String RoiInfo,           Long pts ) | 入参：参数名：encoder参数类型：MediaCodec参数说明： 编码器实例 参数名：RoiInfo参数类型：String参数说明： RoiEncode区域和deltaQP值 参数名：pts参数类型：Long参数说明： 当前帧时间戳（单位us） 返回值：参数类型：int参数说明: 入参是否满足条件参数取值：0---入参满足条件 |
+| boolean isRoiEncodeEnable(MediaCodec)                        | 入参：参数名：encoder参数类型：MediaCodec参数说明： 编码器实例 返回值：参数类型：boolean参数说明: RoiEncode功能是否生效参数取值：true---功能生效     false---功能未生效 |
+
+## **调用步骤**
+
+### **2.1 获取版本号**
+
+```
+**int version = mRoiEncodeUnit.getVersion();**
+```
+
+
+
+### **2.2、是否支持RoiEncode功能**
+
+```
+MediaCodec mEncoder = MediaCodec.createEncoderByType(“video/avc”);**
+
+**boolean isRoiSupported = mRoiEncodeUnit.isRoiEncodeSupported(mEncoder);**
+
+**if (isRoiSupported) {**
+
+**Log.d(“ROI”, “ROI is supported”)**
+
+**} else {**
+
+**Log.d(“ROI”, “ROI is not supported”);**
+
+**}
+```
+
+
+
+### **2.3、Enable RoiEncode功能**
+
+当前平台支持RoiEncode能力后，编码时打开ROI编码功能
+
+```
+if (isRoiSupported) {**
+
+**Log.d(“ROI”, “ROI is supported”);**
+
+**MediaFormat encodeFormat;**
+
+**int enableflag = mRoiEncodeUnit.enableRoiEncode(encodeFormat, 1);//enable**
+
+**if (enableflag != 0) {**
+
+**Log.d(“ROI”, “input paramter is invalid”);**
+
+**}**
+
+**}
+```
+
+
+
+### **2.4、设置ROI编码参数**
+
+通过RoiEncodeUnit实例的enableRoiEncode方法打开ROI编码能力后，对每一帧设置RoiEncode参数:
+
+```
+if (enableflag == 0) {**
+
+**ByteBuffer\[\] inputBuffers = mEncode.getInputBuffers();  
+int inputBufferIndex = mEncoder.dequeueInputBuffer(-1);  
+if (inputBufferIndex \>= 0) {  
+pts = computePresentationTime(generateIndex);  
+String ROI = “100,110-200,210=-6;300,300-400,400=-6”;**
+
+**int flag = mRoiEncodeUnit.setRoiParameter(mEncoder, ROI, pts);**
+
+**if(flag != 0) {**
+
+**Log.d(“ROI”, “input parameter is invalid”);**
+
+**}  
+ByteBuffer inputBuffer = inputBuffers\[inputBufferIndex\];  
+inputBuffer.clear();  
+inputBuffer.put(input);  
+mEncoder.queueInputBuffer(inputBufferIndex, 0, input.length, pts, 0);  
+generateIndex += 1;**
+
+**}
+```
+
+**备注：**
+
+int setRoiParameter(MediaCodec mEncoder,String RoiInfo, long pts);
+
+String RoiInfo设置方法：
+
+100,110-200,210=-6:
+
+100,110为矩形区域左上角顶点坐标，100为y坐标，110为x坐标
+
+200,210为矩形区域右下角顶点坐标，200为y坐标，210为x坐标
+
+-6为该矩形区域的deltaQP值，该值建议取值范围\[-6，6\]，数值越小，该矩形区域最终编码质量越高。
+
+### **2.5、获取RoiEncode状态**
+
+设置RoiEncode参数后，可以获取该帧RoiEncode状态
+
+```
+if (flag == 0) {**
+
+**mEncoder.dequeueOutPutBuffer();**
+
+**boolean flag = mRoiEncodeUnit.isRoiEncodeEnable(mEncoder);**
+
+**if （flag） {**
+
+**Log.d(“ROI”, “RoiEncode is in working”);**
+
+**}**
+
+**}
+```
+
+
+
+# **版本更新说明**
+
+|        |                       |
+| ------ | --------------------- |
+| 版本号 | 更新内容              |
+| 1.0.0  | 支持RoiEncode编码能力 |
+|        |                       |
+
+ 
+
+# **常见问题及FAQ**
+
+1、ROI编码参数deltaQP范围？
+
+支持范围为\[-31,30\]；建议设置范围\[-6,6\]；
+
+2、返回值
+
+接口返回值请参考接口说明
+
+3、getVersion版本号说明
+
+初始返回值为10000表示1.0.0版本
\ No newline at end of file