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 * @addtogroup Core 18 * @{ 19 * 20 * @brief The Core module provides basic backbone capabilities for media frameworks, 21 * including functions such as memory, error codes, and media data structures. 22 * 23 * @syscap SystemCapability.Multimedia.Media.Core 24 * @since 9 25 */ 26 27 /** 28 * @file native_avbuffer.h 29 * 30 * @brief Declared the function interface of media data structure AVBuffer. 31 * 32 * @kit AVCodecKit 33 * @library libnative_media_core.so 34 * @syscap SystemCapability.Multimedia.Media.Core 35 * @since 11 36 */ 37 38 #ifndef NATIVE_AVBUFFER_H 39 #define NATIVE_AVBUFFER_H 40 41 #include <stdint.h> 42 #include <stdio.h> 43 #include "native_averrors.h" 44 #include "native_avformat.h" 45 #include "native_avbuffer_info.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 /** 52 * @brief Forward declaration of OH_AVBuffer. 53 * 54 * @since 11 55 */ 56 typedef struct OH_AVBuffer OH_AVBuffer; 57 /** 58 * @brief Forward declaration of OH_NativeBuffer. 59 * 60 * @since 11 61 */ 62 typedef struct OH_NativeBuffer OH_NativeBuffer; 63 64 /** 65 * @brief Create an OH_AVBuffer instance, It should be noted that the life cycle of the OH_AVBuffer instance pointed 66 * to by the return value * needs to be manually released by {@link OH_AVBuffer_Destroy}. 67 * @syscap SystemCapability.Multimedia.Media.Core 68 * @param capacity the buffer's capacity, bytes 69 * @return Returns a pointer to an OH_AVBuffer instance if the execution is successful, otherwise returns nullptr. 70 * Possible failure causes: 1. capacity <= 0. 2. create allocator failed. 3. create OH_AVBuffer failed. 71 * 4. created buffer memory is nullptr. 5. created buffer memory's addr is nullptr. 6. failed to new OH_AVBuffer. 72 * @since 11 73 */ 74 OH_AVBuffer *OH_AVBuffer_Create(int32_t capacity); 75 76 /** 77 * @brief Clear the internal resources of the buffer and destroy the buffer instance. 78 * @syscap SystemCapability.Multimedia.Media.Core 79 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 80 * @return Function result code. 81 * {@link AV_ERR_OK} if the execution is successful. 82 * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr or buffer's magic error. 83 * {@link AV_ERR_OPERATE_NOT_PERMIT} if input buffer is not user created. 84 * @since 11 85 */ 86 OH_AVErrCode OH_AVBuffer_Destroy(OH_AVBuffer *buffer); 87 88 /** 89 * @brief Get the buffer's attribute. 90 * @syscap SystemCapability.Multimedia.Media.Core 91 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 92 * @param attr Encapsulate OH_AVCodecBufferAttr structure instance pointer, please refer to 93 * {@link OH_AVCodecBufferAttr} 94 * @return Function result code. 95 * {@link AV_ERR_OK} if the execution is successful. 96 * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr, buffer's magic error, 97 * input buffer's buffer is nulllptr or attr is nullptr. 98 * @since 11 99 */ 100 OH_AVErrCode OH_AVBuffer_GetBufferAttr(OH_AVBuffer *buffer, OH_AVCodecBufferAttr *attr); 101 102 /** 103 * @brief Set the buffer's attribute. 104 * @syscap SystemCapability.Multimedia.Media.Core 105 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 106 * @param attr Encapsulate OH_AVCodecBufferAttr structure instance pointer, please refer to 107 * {@link OH_AVCodecBufferAttr} 108 * @return Function result code. 109 * {@link AV_ERR_OK} if the execution is successful. 110 * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr, buffer's magic error, 111 * input buffer's buffer is nulllptr, attr is nullptr, the size or offset of input buffer's memory is invalid. 112 * @since 11 113 */ 114 OH_AVErrCode OH_AVBuffer_SetBufferAttr(OH_AVBuffer *buffer, const OH_AVCodecBufferAttr *attr); 115 116 /** 117 * @brief Get the buffer's parameter. It should be noted that the life cycle of the OH_AVFormat instance pointed to 118 * by the return value * needs to be manually released by {@link OH_AVFormat_Destroy}. 119 * @syscap SystemCapability.Multimedia.Media.Core 120 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 121 * @return Returns Encapsulate OH_AVFormat structure instance pointer if the execution is successful, 122 * otherwise returns nullptr. Possible failure causes: 1. input buffer is nullptr. 2. buffer's magic error. 123 * 3. input buffer's buffer is nulllptr. 4. buffer's meta is nullptr. 124 * @since 11 125 */ 126 OH_AVFormat *OH_AVBuffer_GetParameter(OH_AVBuffer *buffer); 127 128 /** 129 * @brief Set the buffer's parameter. 130 * @syscap SystemCapability.Multimedia.Media.Core 131 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 132 * @param format Encapsulate OH_AVFormat structure instance pointer 133 * @return Function result code. 134 * {@link AV_ERR_OK} if the execution is successful. 135 * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr, buffer's magic error, 136 * input buffer's buffer is nulllptr, input format is nullptr or input meta is nullptr. 137 * @since 11 138 */ 139 OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *format); 140 141 /** 142 * @brief Get the buffer's virtual address. 143 * @syscap SystemCapability.Multimedia.Media.Core 144 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 145 * @return the buffer's virtual address if the buffer is valid, otherwise nullptr 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 uint8_t *OH_AVBuffer_GetAddr(OH_AVBuffer *buffer); 151 152 /** 153 * @brief Get the buffer's capacity 154 * @syscap SystemCapability.Multimedia.Media.Core 155 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 156 * @return the buffer's capacity if the buffer is valid, otherwise -1 157 * Possible failure causes: 1. input buffer is nullptr. 2. buffer's magic error. 158 * 3. input buffer's buffer is nulllptr. 4. buffer's memory is nullptr. 159 * @since 11 160 */ 161 int32_t OH_AVBuffer_GetCapacity(OH_AVBuffer *buffer); 162 163 /** 164 * @brief Get the OH_NativeBuffer instance pointer,It should be noted that the life cycle of the OH_AVBuffer 165 * instance pointed to by the return value * needs to be manually released by {@link OH_NativeBuffer_Unreference}. 166 * @syscap SystemCapability.Multimedia.Media.Core 167 * @param buffer Encapsulate OH_AVBuffer structure instance pointer 168 * @return Returns Encapsulate OH_NativeBuffer structure instance pointer is successful, otherwise returns nullptr 169 * Possible failure causes: 1. input buffer is nullptr. 2. buffer's magic error. 170 * 3. input buffer's buffer is nulllptr. 4. buffer's memory is nullptr. 5. surfaceBuffer is nullptr. 171 * @since 11 172 */ 173 OH_NativeBuffer *OH_AVBuffer_GetNativeBuffer(OH_AVBuffer *buffer); 174 175 #ifdef __cplusplus 176 } 177 #endif 178 179 #endif // NATIVE_AVBUFFER_H 180 /** @} */