1# native_avbuffer.h 2 3## Overview 4 5The file declares the functions of the media struct AVBuffer. 6 7**File to include**: <multimedia/player_framework/native_avbuffer.h> 8 9**Library**: libnative_media_core.so 10 11**System capability**: SystemCapability.Multimedia.Media.Core 12 13**Since**: 11 14 15**Related module**: [Core](capi-core.md) 16 17**Sample**: [AVCodec](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Media/AVCodec) 18 19## Summary 20 21### Structs 22 23| Name| typedef Keyword| Description| 24| -- | -- | -- | 25| [OH_AVBuffer](capi-core-oh-avbuffer.md) | OH_AVBuffer | Describes a native object for the media memory interface.| 26| [OH_NativeBuffer](capi-core-oh-nativebuffer.md) | OH_NativeBuffer | Describes a native object for the graphics memory interface.| 27 28### Functions 29 30| Name| Description| 31| -- | -- | 32| [OH_AVBuffer *OH_AVBuffer_Create(int32_t capacity)](#oh_avbuffer_create) | Creates an OH_AVBuffer instance. You must call [OH_AVBuffer_Destroy](capi-native-avbuffer-h.md#oh_avbuffer_destroy) to manually release the OH_AVBuffer instance returned.| 33| [OH_AVErrCode OH_AVBuffer_Destroy(OH_AVBuffer *buffer)](#oh_avbuffer_destroy) | Releases an OH_AVBuffer instance. A buffer cannot be destroyed repeatedly.| 34| [OH_AVErrCode OH_AVBuffer_GetBufferAttr(OH_AVBuffer *buffer, OH_AVCodecBufferAttr *attr)](#oh_avbuffer_getbufferattr) | Obtains the basic attributes, including **pts**, **size**, **offset**, and **flags**, of a buffer.| 35| [OH_AVErrCode OH_AVBuffer_SetBufferAttr(OH_AVBuffer *buffer, const OH_AVCodecBufferAttr *attr)](#oh_avbuffer_setbufferattr) | Sets the basic attributes, including **pts**, **size**, **offset**, and **flags**, of a buffer.| 36| [OH_AVFormat *OH_AVBuffer_GetParameter(OH_AVBuffer *buffer)](#oh_avbuffer_getparameter) | Obtains parameters except basic attributes of a buffer. The information is carried in an OH_AVFormat instance. You must call [OH_AVFormat_Destroy](capi-native-avformat-h.md#oh_avformat_destroy) to manually release the OH_AVFormat instance returned.| 37| [OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *format)](#oh_avbuffer_setparameter) | Sets parameters except basic attributes of a buffer. The information is carried in an OH_AVFormat instance.| 38| [uint8_t *OH_AVBuffer_GetAddr(OH_AVBuffer *buffer)](#oh_avbuffer_getaddr) | Obtains the virtual address of a data buffer.| 39| [int32_t OH_AVBuffer_GetCapacity(OH_AVBuffer *buffer)](#oh_avbuffer_getcapacity) | Obtains the capacity (in bytes) of a buffer.| 40| [OH_NativeBuffer *OH_AVBuffer_GetNativeBuffer(OH_AVBuffer *buffer)](#oh_avbuffer_getnativebuffer) | Obtains the pointer to an OH_NativeBuffer instance. You must call **OH_NativeBuffer_Unreference** to release the OH_NativeBuffer instance returned.| 41 42## Function Description 43 44### OH_AVBuffer_Create() 45 46``` 47OH_AVBuffer *OH_AVBuffer_Create(int32_t capacity) 48``` 49 50**Description** 51 52Creates an OH_AVBuffer instance. You must call [OH_AVBuffer_Destroy](capi-native-avbuffer-h.md#oh_avbuffer_destroy) to manually release the OH_AVBuffer instance returned. 53 54**System capability**: SystemCapability.Multimedia.Media.Core 55 56**Since**: 11 57 58 59**Parameters** 60 61| Name| Description| 62| -- | -- | 63| int32_t capacity | Size of the created memory, in bytes.| 64 65**Returns** 66 67| Type| Description| 68| -- | -- | 69| [OH_AVBuffer](capi-core-oh-avbuffer.md) * | Pointer to the OH_AVBuffer instance created. If the operation fails, NULL is returned.<br> The possible causes of an operation failure are as follows:<br>1. The value of **capacity** is less than or equal to **0**.<br>2. An internal error occurs, or the system does not have resources.| 70 71### OH_AVBuffer_Destroy() 72 73``` 74OH_AVErrCode OH_AVBuffer_Destroy(OH_AVBuffer *buffer) 75``` 76 77**Description** 78 79Releases an OH_AVBuffer instance. A buffer cannot be destroyed repeatedly. 80 81**System capability**: SystemCapability.Multimedia.Media.Core 82 83**Since**: 11 84 85 86**Parameters** 87 88| Name| Description| 89| -- | -- | 90| [OH_AVBuffer](capi-core-oh-avbuffer.md) *buffer | Pointer to an OH_AVBuffer instance.| 91 92**Returns** 93 94| Type| Description| 95| -- | -- | 96| [OH_AVErrCode](capi-native-averrors-h.md#oh_averrcode) | **AV_ERR_OK**: The operation is successful.<br> **AV_ERR_INVALID_VAL**: The value of **buffer** is nullptr or fails format verification.<br> **AV_ERR_OPERATE_NOT_PERMIT**: The input buffer is not created by the user.| 97 98### OH_AVBuffer_GetBufferAttr() 99 100``` 101OH_AVErrCode OH_AVBuffer_GetBufferAttr(OH_AVBuffer *buffer, OH_AVCodecBufferAttr *attr) 102``` 103 104**Description** 105 106Obtains the basic attributes, including **pts**, **size**, **offset**, and **flags**, of a buffer. 107 108**System capability**: SystemCapability.Multimedia.Media.Core 109 110**Since**: 11 111 112 113**Parameters** 114 115| Name| Description| 116| -- | -- | 117| [OH_AVBuffer](capi-core-oh-avbuffer.md) *buffer | Pointer to an OH_AVBuffer instance.| 118| [OH_AVCodecBufferAttr](capi-core-oh-avcodecbufferattr.md) *attr | Pointer to an OH_AVCodecBufferAttr instance.| 119 120**Returns** 121 122| Type| Description| 123| -- | -- | 124| [OH_AVErrCode](capi-native-averrors-h.md#oh_averrcode) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The possible causes are as follows:<br>1. The value of **buffer** or **attr** is nullptr.<br>2. The value of **buffer** fails parameter structure verification.| 125 126### OH_AVBuffer_SetBufferAttr() 127 128``` 129OH_AVErrCode OH_AVBuffer_SetBufferAttr(OH_AVBuffer *buffer, const OH_AVCodecBufferAttr *attr) 130``` 131 132**Description** 133 134Sets the basic attributes, including **pts**, **size**, **offset**, and **flags**, of a buffer. 135 136**System capability**: SystemCapability.Multimedia.Media.Core 137 138**Since**: 11 139 140 141**Parameters** 142 143| Name| Description| 144| -- | -- | 145| [OH_AVBuffer](capi-core-oh-avbuffer.md) *buffer | Pointer to an OH_AVBuffer instance.| 146| [const OH_AVCodecBufferAttr](capi-core-oh-avcodecbufferattr.md) *attr | Pointer to an OH_AVCodecBufferAttr instance.| 147 148**Returns** 149 150| Type| Description| 151| -- | -- | 152| [OH_AVErrCode](capi-native-averrors-h.md#oh_averrcode) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The possible causes are as follows:<br>1. The value of **buffer** or **attr** is nullptr.<br>2. The value of **buffer** fails parameter structure verification.<br>3. The memory size or offset of the buffer is invalid.| 153 154### OH_AVBuffer_GetParameter() 155 156``` 157OH_AVFormat *OH_AVBuffer_GetParameter(OH_AVBuffer *buffer) 158``` 159 160**Description** 161 162Obtains parameters except basic attributes of a buffer. The information is carried in an OH_AVFormat instance. You must call [OH_AVFormat_Destroy](capi-native-avformat-h.md#oh_avformat_destroy) to manually release the OH_AVFormat instance returned. 163 164**System capability**: SystemCapability.Multimedia.Media.Core 165 166**Since**: 11 167 168 169**Parameters** 170 171| Name| Description| 172| -- | -- | 173| [OH_AVBuffer](capi-core-oh-avbuffer.md) *buffer | Pointer to an OH_AVBuffer instance.| 174 175**Returns** 176 177| Type| Description| 178| -- | -- | 179| [OH_AVFormat](capi-core-oh-avformat.md) * | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The possible causes are as follows:<br>1. The value of **buffer** is nullptr.<br>2. The meta of the buffer is nullptr.<br>3. The value of **buffer** fails parameter structure verification.| 180 181### OH_AVBuffer_SetParameter() 182 183``` 184OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *format) 185``` 186 187**Description** 188 189Sets parameters except basic attributes of a buffer. The information is carried in an OH_AVFormat instance. 190 191**System capability**: SystemCapability.Multimedia.Media.Core 192 193**Since**: 11 194 195 196**Parameters** 197 198| Name| Description| 199| -- | -- | 200| [OH_AVBuffer](capi-core-oh-avbuffer.md) *buffer | Pointer to an OH_AVBuffer instance.| 201| [const OH_AVFormat](capi-core-oh-avformat.md) *format | Pointer to an OH_AVFormat instance.| 202 203**Returns** 204 205| Type| Description| 206| -- | -- | 207| [OH_AVErrCode](capi-native-averrors-h.md#oh_averrcode) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The possible causes are as follows:<br>1. The value of **buffer** or **format** is nullptr.<br>2. The meta of the buffer is nullptr.<br>3. The value of **buffer** fails parameter structure verification.| 208 209### OH_AVBuffer_GetAddr() 210 211``` 212uint8_t *OH_AVBuffer_GetAddr(OH_AVBuffer *buffer) 213``` 214 215**Description** 216 217Obtains the virtual address of a data buffer. 218 219The capability to obtain virtual addresses varies in scenarios, as described in the table below. 220 221**Encoding** 222 223| Mode| Data Filling Mode| Capability to Obtain Virtual Addresses| 224| --------------- | -------- | -------- | 225| Surface| OnNeedInputBuffer input | Not supported| 226| Surface| OnNewOutputBuffer output | Supported| 227| Buffer | OnNeedInputBuffer input | Supported| 228| Buffer | OnNewOutputBuffer output | Supported| 229 230**Decoding** 231 232| Mode| Data Filling Mode| Capability to Obtain Virtual Addresses| 233| --------------- | -------- | -------- | 234| Surface| OnNeedInputBuffer input | Supported| 235| Surface| OnNewOutputBuffer output | Not supported| 236| Buffer | OnNeedInputBuffer input | Supported| 237| Buffer | OnNewOutputBuffer output | Supported| 238 239**System capability**: SystemCapability.Multimedia.Media.Core 240 241**Since**: 11 242 243 244**Parameters** 245 246| Name| Description| 247| -- | -- | 248| [OH_AVBuffer](capi-core-oh-avbuffer.md) *buffer | Pointer to an OH_AVBuffer instance.| 249 250**Returns** 251 252| Type| Description| 253| -- | -- | 254| uint8_t * | Virtual address. If the operation fails, NULL is returned.<br> The possible causes of an operation failure are as follows:<br> 1. The value of **buffer** is a null pointer.<br>2. The value of **OH_AVBuffer** fails parameter structure verification.<br>3. An internal error occurs.| 255 256### OH_AVBuffer_GetCapacity() 257 258``` 259int32_t OH_AVBuffer_GetCapacity(OH_AVBuffer *buffer) 260``` 261 262**Description** 263 264Obtains the capacity (in bytes) of a buffer. 265 266**System capability**: SystemCapability.Multimedia.Media.Core 267 268**Since**: 11 269 270 271**Parameters** 272 273| Name| Description| 274| -- | -- | 275| [OH_AVBuffer](capi-core-oh-avbuffer.md) *buffer | Pointer to an OH_AVBuffer instance.| 276 277**Returns** 278 279| Type| Description| 280| -- | -- | 281| int32_t | Capacity. If the operation fails, **-1** is returned.<br> The possible causes of an operation failure are as follows:<br>1. The value of **buffer** is a null pointer.<br>2. The value of **OH_AVBuffer** fails parameter structure verification.<br>3. An internal error occurs.| 282 283### OH_AVBuffer_GetNativeBuffer() 284 285``` 286OH_NativeBuffer *OH_AVBuffer_GetNativeBuffer(OH_AVBuffer *buffer) 287``` 288 289**Description** 290 291Obtains the pointer to an OH_NativeBuffer instance. You must call [OH_NativeBuffer_Unreference](../apis-arkgraphics2d/capi-native-buffer-h.md#oh_nativebuffer_unreference) to manually release the OH_NativeBuffer instance returned. 292 293**System capability**: SystemCapability.Multimedia.Media.Core 294 295**Since**: 11 296 297 298**Parameters** 299 300| Name| Description| 301| -- | -- | 302| [OH_AVBuffer](capi-core-oh-avbuffer.md) *buffer | Pointer to an OH_AVBuffer instance.| 303 304**Returns** 305 306| Type| Description| 307| -- | -- | 308| OH_NativeBuffer * | Pointer to the OH_NativeBuffer instance created. If the operation fails, NULL is returned.<br> The possible causes of an operation failure are as follows:<br>1. The value of **buffer** is a null pointer.<br>2. The value of **OH_AVBuffer** fails parameter structure verification.<br>3. An internal error occurs.| 309 310<!--no_check-->