!3638 增加image reciever接口说明

Merge pull request !3638 from 张晓波/master

zh-cn/application-dev/reference/apis/js-apis-image.md

@@ -66,9 +66,11 @@ image.createPixelMap(Color, opts, (pixelmap) => {
 
  ### 属性
 
-| 名称                    | 类型    | 可读 | 可写 | 说明                                                         |
-| ----------------------- | ------- | ---- | ---- | ------------------------------------------------------------ |
-| isEditable<sup>7+</sup> | boolean | 是   | 否   | 设定是否图像像素可被编辑。<br/>**系统能力：** SystemCapability.Multimedia.Image |
+**系统能力： ** SystemCapability.Multimedia.Image
+
+| 名称                    | 类型    | 可读 | 可写 | 说明                       |
+| ----------------------- | ------- | ---- | ---- | -------------------------- |
+| isEditable<sup>7+</sup> | boolean | 是   | 否   | 设定是否图像像素可被编辑。 |
 
 ### readPixelsToBuffer<sup>7+</sup>
 
@@ -514,9 +516,11 @@ const imageSourceApi = image.createImageSource(0)
 
 ### 属性
 
+**系统能力： ** SystemCapability.Multimedia.Image
+
 | 名称             | 类型           | 可读 | 可写 | 说明                                                         |
 | ---------------- | -------------- | ---- | ---- | ------------------------------------------------------------ |
-| supportedFormats | Array\<string> | 是   | 否   | 支持的图片格式，包括：png，jpeg，wbmp，bmp，gif，webp，heif等。<br/>**系统能力：** SystemCapability.Multimedia.Image |
+| supportedFormats | Array\<string> | 是   | 否   | 支持的图片格式，包括：png，jpeg，wbmp，bmp，gif，webp，heif等。 |
 
 ### getImageInfo
 
@@ -793,9 +797,11 @@ const imagePackerApi = image.createImagePacker();
 
 ### 属性
 
-| 名称             | 类型           | 可读 | 可写 | 说明                                                         |
-| ---------------- | -------------- | ---- | ---- | ------------------------------------------------------------ |
-| supportedFormats | Array\<string> | 是   | 否   | 图片打包支持的格式，jpeg。<br/>**系统能力：** SystemCapability.Multimedia.Image |
+**系统能力： ** SystemCapability.Multimedia.Image
+
+| 名称             | 类型           | 可读 | 可写 | 说明                       |
+| ---------------- | -------------- | ---- | ---- | -------------------------- |
+| supportedFormats | Array\<string> | 是   | 否   | 图片打包支持的格式，jpeg。 |
 
 ### packing
 
@@ -883,10 +889,10 @@ packing(source: PixelMap, option: PackingOption): Promise<Array\<ArrayBuffer>>
 
 **参数：**
 
-| 参数名 | 类型                            | 必填 | 说明           |
-| ------ | ------------------------------- | ---- | -------------- |
+| 参数名 | 类型                            | 必填 | 说明               |
+| ------ | ------------------------------- | ---- | ------------------ |
 | source | [PixelMap](#pixelmap)           | 是   | 打包的PixelMap源。 |
-| option | [PackingOption](#packingoption) | 是   | 设置打包参数。 |
+| option | [PackingOption](#packingoption) | 是   | 设置打包参数。     |
 
 **返回值：**
 
@@ -944,24 +950,357 @@ release(): Promise\<void>
             }).catch((error)=>{}) 
 ```
 
+## image.createImageReceiver<sup>9+</sup>
+
+ createImageReceiver(width: number, height: number, format: number, capacity: number): ImageReceiver
+
+通过宽、高、图片格式、容量创建imagereceiver实例。
+
+**系统能力： ** SystemCapability.Multimedia.Image.ImageReceiver
+
+**参数：**
+
+| 名称     | 类型   | 必填 | 说明                                  |
+| -------- | ------ | ---- | ------------------------------------- |
+| width    | number | 是   | imagereceiver将生成的图像的默认宽度。 |
+| height   | number | 是   | imagereceiver将生成的图像的默认高度。 |
+| format   | number | 是   | imagereceiver将生成的图像格式。       |
+| capacity | number | 是   | 同时访问的最大图像数。                |
+
+**返回值：**
+
+| 类型          | 说明                                      |
+| ------------- | ----------------------------------------- |
+| ImageReceiver | 如果操作成功，则返回 ImageReceiver 实例。 |
+
+**示例：**
+
+```js
+var receiver = image.createImageReceiver(8192, 8, 4, 8)
+```
+
+## ImageReceiver<sup>9+</sup>
+
+图像接收类，用于获取组件surface id，接收最新的图片和读取下一张图片，以及释放 ImageReceiver 实例。在调用各方法前需要先创建 ImageReceiver 实例。
+
+### 属性
+
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image.ImageReceiver
+
+| 名称     | 类型                         | 可读 | 可写 | 说明               |
+| -------- | ---------------------------- | ---- | ---- | ------------------ |
+| size     | [Size](#size)                | 是   | 否   | 图片大小。         |
+| capacity | number                       | 是   | 否   | 同时访问的图像数。 |
+| format   | [ImageFormat](#imageformat9) | 是   | 否   | 图像格式。         |
+
+### getReceivingSurfaceId<sup>9+</sup>
+
+getReceivingSurfaceId(callback: AsyncCallback\<string>): void
+
+用于获取一个surface id并使用callback返回结果。
+
+**系统能力： ** SystemCapability.Multimedia.Image.ImageReceiver
+
+**参数：**
+
+| 名称     | 类型                   | 必填 | 说明                         |
+| -------- | ---------------------- | ---- | ---------------------------- |
+| callback | AsyncCallback\<string> | 是   | 使用callback返回surface id。 |
+
+**示例:**
+
+```js
+ receiver.getReceivingSurfaceId((err, id) => {});
+```
+
+### getReceivingSurfaceId<sup>9+</sup>
+
+getReceivingSurfaceId(): Promise\<string>
+
+用于获取一个surface id并使用promise返回结果。
+
+**系统能力： ** SystemCapability.Multimedia.Image.ImageReceiver
+
+**返回值：**
+
+| 类型             | 说明                 |
+| ---------------- | -------------------- |
+| Promise\<string> | 异步返回surface id。 |
+
+**示例：**
+
+```js
+receiver.getReceivingSurfaceId().then( id => { 
+            }).catch(error => {
+            })
+```
+
+### readLatestImage<sup>9+</sup>
+
+readLatestImage(callback: AsyncCallback\<Image>): void
+
+从 ImageReceiver读取最新的图片，并使用callback返回结果。
+
+**系统能力： ** SystemCapability.Multimedia.Image.ImageReceiver
+
+**参数：**
+
+| 名称     | 类型                            | 必填 | 说明                   |
+| -------- | ------------------------------- | ---- | ---------------------- |
+| callback | AsyncCallback<[Image](#image8)> | 是   | callback返回最新图像。 |
+
+**示例：**
+
+```js
+ receiver.readLatestImage((err, img) => { });
+```
+
+### readLatestImage<sup>9+</sup>
+
+readLatestImage(): Promise\<Image>
+
+从 ImageReceiver读取最新的图片，并使用promise返回结果。
+
+**系统能力： ** SystemCapability.Multimedia.Image.ImageReceiver
+
+**返回值：**
+
+| 类型                      | 说明               |
+| ------------------------- | ------------------ |
+| Promise<[Image](#image8)> | 异步返回最新图片。 |
+
+**示例：**
+
+```js
+receiver.readLatestImage().then(img => {})
+	.catch(error => {})
+```
+
+### readNextImage<sup>9+</sup>
+
+readNextImage(callback: AsyncCallback\<Image>): void
+
+从 ImageReceiver读取下一张图片，并使用callback返回结果。
+
+**系统能力： ** SystemCapability.Multimedia.Image.ImageReceiver
+
+**参数：**
+
+| 名称     | 类型                            | 必填 | 说明                     |
+| -------- | ------------------------------- | ---- | ------------------------ |
+| callback | AsyncCallback<[Image](#image8)> | 是   | callback返回下一张图片。 |
+
+**示例：**
+
+```js
+receiver.readNextImage((err, img) => {});
+```
+
+### readNextImage<sup>9+</sup>
+
+readNextImage(): Promise\<Image>
+
+从 ImageReceiver读取下一张图片，并使用promise返回结果。
+
+**系统能力： ** SystemCapability.Multimedia.Image.ImageReceiver
+
+**返回值：**
+
+| 类型                      | 说明                 |
+| ------------------------- | -------------------- |
+| Promise<[Image](#image8)> | 异步返回下一张图片。 |
+
+**示例：**
+
+```js
+ receiver.readNextImage().then(img => {
+            }).catch(error => {
+            })
+```
+
+### on<sup>9+</sup>
+
+on(type: 'imageArrival', callback: AsyncCallback\<void>): void
+
+接收图片时注册回调。
+
+**系统能力： ** SystemCapability.Multimedia.Image.ImageReceiver
+
+**参数：**
+
+| 名称     | 类型                 | 必填 | 说明                                                   |
+| -------- | -------------------- | ---- | ------------------------------------------------------ |
+| type     | imageArrival         | 是   | 注册事件的类型，固定为'imageArrival'，接收图片时触发。 |
+| callback | AsyncCallback\<void> | 是   | 注册的事件回调。                                       |
+
+**示例：**
+
+```js
+ receiver.on('imageArrival', () => {})
+```
+
+### release<sup>9+</sup>
+
+ release(callback: AsyncCallback\<void>): void
+
+释放ImageReceiver实例并使用回调返回结果。
+
+**系统能力： ** SystemCapability.Multimedia.Image.ImageReceiver
+
+**参数：**
+
+| 名称     | 类型                 | 必填 | 说明           |
+| -------- | -------------------- | ---- | -------------- |
+| callback | AsyncCallback\<void> | 是   | 返回操作结果。 |
+
+**示例：**
+
+```js
+ receiver.release(() => {})
+```
+
+### release<sup>9+</sup>
+
+release(): Promise\<void>
+
+释放ImageReceiver实例并使用promise返回结果。
+
+**系统能力： ** SystemCapability.Multimedia.Image.ImageReceiver
+
+**返回值：**
+
+| 类型           | 说明                    |
+| -------------- | ----------------------- |
+| Promise\<void> | 用promise返回操作结果。 |
+
+**示例：**
+
+```js
+ receiver.release().then(() => {})
+ 	.catch(error => {})
+```
+
+## Image<sup>9+</sup>
+
+提供基本的图像操作，包括获取图像信息、读写图像数据。调用readNextImage和readLatestImage接口时会返回image。
+
+### 属性
+
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image.Core
+
+| 名称     | 类型               | 可读 | 可写 | 说明                         |
+| -------- | ------------------ | ---- | ---- | ---------------------------- |
+| clipRect | [Region](#region8) | 是   | 是   | 设置或获取要裁剪的图像区域。 |
+| size     | [Size](#size)      | 是   | 否   | 图像大小。                   |
+| format   | number             | 是   | 否   | 图像格式。                   |
+
+### getComponent<sup>9+</sup>
+
+getComponent(componentType: ComponentType, callback: AsyncCallback\<Component>): void
+
+根据图像的组件类型从图像中获取组件缓存并使用callback返回结果。
+
+**系统能力： ** SystemCapability.Multimedia.Image.Core
+
+**参数：**
+
+| 名称          | 类型                                    | 必填 | 说明                 |
+| ------------- | --------------------------------------- | ---- | -------------------- |
+| componentType | [ComponentType](#componenttype8)        | 是   | 图像的组件类型。     |
+| callback      | AsyncCallback<[Component](#component8)> | 是   | 用于返回组件缓冲区。 |
+
+**示例：**
+
+```js
+ img.getComponent(4, (err, component) => {})
+```
+
+### getComponent<sup>9+</sup>
+
+getComponent(componentType: ComponentType): Promise\<Component>
+
+根据图像的组件类型从图像中获取组件缓存并使用promise方式返回结果。
+
+**系统能力： ** SystemCapability.Multimedia.Image.Core
+
+**参数：**
+
+| 名称          | 类型                             | 必填 | 说明             |
+| ------------- | -------------------------------- | ---- | ---------------- |
+| componentType | [ComponentType](#componenttype8) | 是   | 图像的组件类型。 |
+
+**返回值：**
+
+| 类型                              | 说明                              |
+| --------------------------------- | --------------------------------- |
+| Promise<[Component](#component8)> | 用于返回组件缓冲区的promise实例。 |
+
+**示例：**
+
+```js
+img.getComponent(4).then(component => { })
+```
+
+### release<sup>9+</sup>
+
+release(callback: AsyncCallback\<void>): void
+
+释放当前图像并使用callback返回结果。在接收另一个图像前必须先释放对应资源。
+
+**系统能力： ** SystemCapability.Multimedia.Image.Core
+
+**参数：**
+
+| 名称     | 类型                 | 必填 | 说明           |
+| -------- | -------------------- | ---- | -------------- |
+| callback | AsyncCallback\<void> | 是   | 返回操作结果。 |
+
+**示例：**
+
+```js
+img.release(() =>{ }) 
+```
+
+### release<sup>9+</sup>
+
+release(): Promise\<void>
+
+释放当前图像并使用promise返回结果。在接收另一个图像前必须先释放对应资源。
+
+**系统能力： ** SystemCapability.Multimedia.Image.Core
+
+**返回值：**
+
+| 类型           | 说明                  |
+| -------------- | --------------------- |
+| Promise\<void> | promise返回操作结果。 |
+
+**示例：**
+
+```js
+img.release().then(() =>{
+            }).catch(error => {
+            })  
+```
+
 ## PositionArea<sup>7+</sup>
 
 表示图片指定区域内的数据。
 
-**系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
 
 | 名称   | 类型               | 可读 | 可写 | 说明                                                         |
 | ------ | ------------------ | ---- | ---- | ------------------------------------------------------------ |
 | pixels | ArrayBuffer        | 是   | 否   | 像素。                                                       |
 | offset | number             | 是   | 否   | 偏移量。                                                     |
-| stride | number             | 是   | 否   | 像素间距，stride >= region.size.width*4。                     |
+| stride | number             | 是   | 否   | 像素间距，stride >= region.size.width*4。                    |
 | region | [Region](#region8) | 是   | 否   | 区域，按照区域读写。写入的区域宽度加X坐标不能大于原图的宽度，写入的区域高度加Y坐标不能大于原图的高度 |
 
 ## ImageInfo
 
 表示图片信息。
 
-**系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
 
 | 名称 | 类型          | 可读 | 可写 | 说明       |
 | ---- | ------------- | ---- | ---- | ---------- |
@@ -971,7 +1310,7 @@ release(): Promise\<void>
 
 表示图片尺寸。
 
-**系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
 
 | 名称   | 类型   | 可读 | 可写 | 说明           |
 | ------ | ------ | ---- | ---- | -------------- |
@@ -982,7 +1321,7 @@ release(): Promise\<void>
 
 枚举，像素格式。
 
-**系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
 
 | 名称      | 默认值 | 描述              |
 | --------- | ------ | ----------------- |
@@ -994,7 +1333,7 @@ release(): Promise\<void>
 
 枚举，透明度。
 
-**系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
 
 | 名称     | 默认值 | 描述                    |
 | -------- | ------ | ----------------------- |
@@ -1007,7 +1346,7 @@ release(): Promise\<void>
 
 枚举，缩略值。
 
-**系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
 
 | 名称            | 默认值 | 描述                                               |
 | --------------- | ------ | -------------------------------------------------- |
@@ -1016,21 +1355,21 @@ release(): Promise\<void>
 
 ## InitializationOptions<sup>8+</sup>
 
-**系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
 
-| 名称        | 类型                               | 可读 | 可写 | 说明           |
-| ----------- | ---------------------------------- | ---- | ---- | -------------- |
-| alphaType<sup>9+</sup>   | [AlphaType](#alphatype9)           | 是   | 是   | 透明度。       |
-| editable    | boolean                            | 是   | 是   | 是否可编辑。   |
-| pixelFormat | [PixelMapFormat](#pixelmapformat7) | 是   | 是   | 像素格式。     |
-| scaleMode<sup>9+</sup>   | [ScaleMode](#scalemode9)           | 是   | 是   | 缩略值。       |
-| size        | [Size](#size)                      | 是   | 是   | 创建图片大小。 |
+| 名称                   | 类型                               | 可读 | 可写 | 说明           |
+| ---------------------- | ---------------------------------- | ---- | ---- | -------------- |
+| alphaType<sup>9+</sup> | [AlphaType](#alphatype9)           | 是   | 是   | 透明度。       |
+| editable               | boolean                            | 是   | 是   | 是否可编辑。   |
+| pixelFormat            | [PixelMapFormat](#pixelmapformat7) | 是   | 是   | 像素格式。     |
+| scaleMode<sup>9+</sup> | [ScaleMode](#scalemode9)           | 是   | 是   | 缩略值。       |
+| size                   | [Size](#size)                      | 是   | 是   | 创建图片大小。 |
 
 ## DecodingOptions<sup>7+</sup>
 
 解码设置选项。
 
-**系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
 
 | 名称               | 类型                               | 可读 | 可写 | 说明             |
 | ------------------ | ---------------------------------- | ---- | ---- | ---------------- |
@@ -1038,15 +1377,15 @@ release(): Promise\<void>
 | rotate             | number                             | 是   | 是   | 旋转角度。       |
 | editable           | boolean                            | 是   | 是   | 是否可编辑。     |
 | desiredSize        | [Size](#size)                      | 是   | 是   | 期望输出大小。   |
-| desiredRegion      | [Region](#region7)                 | 是   | 是   | 解码区域。       |
+| desiredRegion      | [Region](#region8)                 | 是   | 是   | 解码区域。       |
 | desiredPixelFormat | [PixelMapFormat](#pixelmapformat7) | 是   | 是   | 解码的像素格式。 |
 | index              | numer                              | 是   | 是   | 解码图片序号     |
 
-## Region<sup>7+</sup>
+## Region<sup>8+</sup>
 
 表示区域信息。
 
-**系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
 
 | 名称 | 类型          | 可读 | 可写 | 说明         |
 | ---- | ------------- | ---- | ---- | ------------ |
@@ -1058,7 +1397,7 @@ release(): Promise\<void>
 
 表示图片打包选项。
 
-**系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
 
 | 名称    | 类型   | 可读 | 可写 | 说明           |
 | ------- | ------ | ---- | ---- | -------------- |
@@ -1069,7 +1408,7 @@ release(): Promise\<void>
 
 表示查询图片属性的索引。
 
-**系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
 
 | 名称         | 类型   | 可读 | 可写 | 说明         |
 | ------------ | ------ | ---- | ---- | ------------ |
@@ -1080,7 +1419,7 @@ release(): Promise\<void>
 
 枚举，Exif（Exchangeable image file format）图片信息。
 
-**系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image
 
 | 名称              | 默认值            | 说明                 |
 | ----------------- | ----------------- | -------------------- |
@@ -1093,3 +1432,40 @@ release(): Promise\<void>
 | GPS_LATITUDE_REF  | "GPSLatitudeRef"  | 纬度引用，例如N或S。 |
 | GPS_LONGITUDE_REF | "GPSLongitudeRef" | 经度引用，例如W或E。 |
 
+## ImageFormat<sup>9+</sup>
+
+枚举，图片格式。
+
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image.Core
+
+| 名称         | 默认值 | 描述                  |
+| ------------ | ------ | --------------------- |
+| YCBCR_422_SP | 1000   | YCBCR422 半平面格式。 |
+| JPEG         | 2000   | JPEG编码格式。        |
+
+## ComponentType<sup>8+</sup>
+
+枚举，图像的组件类型。
+
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image.ImageReceiver
+
+| 名称  | 默认值 | 描述        |
+| ----- | ------ | ----------- |
+| YUV_Y | 1      | 亮度信息。  |
+| YUV_U | 2      | 色度信息。  |
+| YUV_V | 3      | 色度信息。  |
+| JPEG  | 4      | Jpeg 类型。 |
+
+## Component<sup>8+</sup>
+
+描述图像颜色分量。
+
+**系统能力： ** 以下各项对应的系统能力均为SystemCapability.Multimedia.Image.Core
+
+| 名称          | 类型                             | 可读 | 可写 | 说明         |
+| ------------- | -------------------------------- | ---- | ---- | ------------ |
+| componentType | [ComponentType](#componenttype8) | 是   | 否   | 组件类型。   |
+| rowStride     | number                           | 是   | 否   | 行距。       |
+| pixelStride   | number                           | 是   | 否   | 像素间距。   |
+| byteBuffer    | ArrayBuffer                      | 是   | 否   | 组件缓冲区。 |
+