1 /* 2 * Copyright (C) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @file native_avbuffer.h 18 * 19 * @brief Provides audio and video buffer. 20 * 21 * @kit AVCodecKit 22 * @library libnative_media_core.so 23 * @syscap SystemCapability.Multimedia.Media.Core 24 * @since 11 25 */ 26 27 #ifndef NATIVE_AVBUFFER_H 28 #define NATIVE_AVBUFFER_H 29 30 #include <stdint.h> 31 #include <stdio.h> 32 #include "native_averrors.h" 33 #include "native_avformat.h" 34 #include "native_avbuffer_info.h" 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /** 41 * @brief Forward declaration of OH_AVBuffer. 42 * 43 * @since 11 44 */ 45 typedef struct OH_AVBuffer OH_AVBuffer; 46 /** 47 * @brief Forward declaration of OH_NativeBuffer. 48 * 49 * @since 11 50 */ 51 typedef struct OH_NativeBuffer OH_NativeBuffer; 52 53 /** 54 * @brief Create an OH_AVBuffer instance, It should be noted that the life cycle of the OH_AVBuffer instance pointed 55 * to by the return value * needs to be manually released by {@link OH_AVBuffer_Destroy}. 56 * @syscap SystemCapability.Multimedia.Media.Core 57 * @param capacity the buffer's capacity, bytes 58 * @return Returns a pointer to an OH_AVBuffer instance if the execution is successful, otherwise returns nullptr. 59 * Possible failure causes: 1. capacity <= 0. 2. create allocator failed. 3. create OH_AVBuffer failed. 60 * 4. created buffer memory is nullptr. 5. created buffer memory's addr is nullptr. 6. failed to new OH_AVBuffer. 61 * @since 11 62 */ 63 OH_AVBuffer *OH_AVBuffer_Create(int32_t capacity); 64 65 /** 66 * @brief Clear the internal resources of the buffer and destroy the buffer instance. 67 * @syscap SystemCapability.Multimedia.Media.Core 68 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 69 * @return Function result code. 70 * {@link AV_ERR_OK} if the execution is successful. 71 * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr or buffer's magic error. 72 * {@link AV_ERR_OPERATE_NOT_PERMIT} if input buffer is not user created. 73 * @since 11 74 */ 75 OH_AVErrCode OH_AVBuffer_Destroy(OH_AVBuffer *buffer); 76 77 /** 78 * @brief Get the buffer's attribute. 79 * @syscap SystemCapability.Multimedia.Media.Core 80 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 81 * @param attr Encapsulate OH_AVCodecBufferAttr structure instance pointer, please refer to 82 * {@link OH_AVCodecBufferAttr} 83 * @return Function result code. 84 * {@link AV_ERR_OK} if the execution is successful. 85 * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr, buffer's magic error, 86 * input buffer's buffer is nulllptr or attr is nullptr. 87 * @since 11 88 */ 89 OH_AVErrCode OH_AVBuffer_GetBufferAttr(OH_AVBuffer *buffer, OH_AVCodecBufferAttr *attr); 90 91 /** 92 * @brief Set the buffer's attribute. 93 * @syscap SystemCapability.Multimedia.Media.Core 94 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 95 * @param attr Encapsulate OH_AVCodecBufferAttr structure instance pointer, please refer to 96 * {@link OH_AVCodecBufferAttr} 97 * @return Function result code. 98 * {@link AV_ERR_OK} if the execution is successful. 99 * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr, buffer's magic error, 100 * input buffer's buffer is nulllptr, attr is nullptr, the size or offset of input buffer's memory is invalid. 101 * @since 11 102 */ 103 OH_AVErrCode OH_AVBuffer_SetBufferAttr(OH_AVBuffer *buffer, const OH_AVCodecBufferAttr *attr); 104 105 /** 106 * @brief Get the buffer's parameter. It should be noted that the life cycle of the OH_AVFormat instance pointed to 107 * by the return value * needs to be manually released by {@link OH_AVFormat_Destroy}. 108 * @syscap SystemCapability.Multimedia.Media.Core 109 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 110 * @return Returns Encapsulate OH_AVFormat structure instance pointer if the execution is successful, 111 * otherwise returns nullptr. Possible failure causes: 1. input buffer is nullptr. 2. buffer's magic error. 112 * 3. input buffer's buffer is nulllptr. 4. buffer's meta is nullptr. 113 * @since 11 114 */ 115 OH_AVFormat *OH_AVBuffer_GetParameter(OH_AVBuffer *buffer); 116 117 /** 118 * @brief Set the buffer's parameter. 119 * @syscap SystemCapability.Multimedia.Media.Core 120 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 121 * @param format Encapsulate OH_AVFormat structure instance pointer 122 * @return Function result code. 123 * {@link AV_ERR_OK} if the execution is successful. 124 * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr, buffer's magic error, 125 * input buffer's buffer is nulllptr, input format is nullptr or input meta is nullptr. 126 * @since 11 127 */ 128 OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *format); 129 130 /** 131 * @brief Get the buffer's virtual address. 132 * @syscap SystemCapability.Multimedia.Media.Core 133 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 134 * @return the buffer's virtual address if the buffer is valid, otherwise nullptr 135 * Possible failure causes: 1. input buffer is nullptr. 2. buffer's magic error. 136 * 3. input buffer's buffer is nulllptr. 4. buffer's memory is nullptr. 137 * @since 11 138 */ 139 uint8_t *OH_AVBuffer_GetAddr(OH_AVBuffer *buffer); 140 141 /** 142 * @brief Get the buffer's capacity 143 * @syscap SystemCapability.Multimedia.Media.Core 144 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 145 * @return the buffer's capacity if the buffer is valid, otherwise -1 146 * Possible failure causes: 1. input buffer is nullptr. 2. buffer's magic error. 147 * 3. input buffer's buffer is nulllptr. 4. buffer's memory is nullptr. 148 * @since 11 149 */ 150 int32_t OH_AVBuffer_GetCapacity(OH_AVBuffer *buffer); 151 152 /** 153 * @brief Get the OH_NativeBuffer instance pointer,It should be noted that the life cycle of the OH_AVBuffer 154 * instance pointed to by the return value * needs to be manually released by {@link OH_NativeBuffer_Unreference}. 155 * @syscap SystemCapability.Multimedia.Media.Core 156 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 157 * @return Returns Encapsulate OH_NativeBuffer structure instance pointer is successful, otherwise returns nullptr 158 * Possible failure causes: 1. input buffer is nullptr. 2. buffer's magic error. 159 * 3. input buffer's buffer is nulllptr. 4. buffer's memory is nullptr. 5. surfaceBuffer is nullptr. 160 * @since 11 161 */ 162 OH_NativeBuffer *OH_AVBuffer_GetNativeBuffer(OH_AVBuffer *buffer); 163 164 #ifdef __cplusplus 165 } 166 #endif 167 168 #endif // NATIVE_AVBUFFER_H 169