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
37extern "C" {
38#endif
39
40/**
41 * @brief Forward declaration of OH_AVBuffer.
42 *
43 * @since 11
44 */
45typedef struct OH_AVBuffer OH_AVBuffer;
46/**
47 * @brief Forward declaration of OH_NativeBuffer.
48 *
49 * @since 11
50 */
51typedef 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 */
63OH_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 */
75OH_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 */
89OH_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 */
103OH_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 */
115OH_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, buffer's magic error, or input meta is nullptr.
126 * @since 11
127 */
128OH_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 */
139uint8_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 */
150int32_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 */
162OH_NativeBuffer *OH_AVBuffer_GetNativeBuffer(OH_AVBuffer *buffer);
163
164#ifdef __cplusplus
165}
166#endif
167
168#endif // NATIVE_AVBUFFER_H
169