1/*
2 * Copyright (c) 2022 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 Audio
18 * @{
19 *
20 * @brief Defines audio-related APIs, including custom data types and functions for loading drivers,
21 * accessing a driver adapter, and rendering and capturing audios.
22 *
23 * @since 1.0
24 * @version 1.0
25 */
26
27/**
28 * @file audio_render.h
29 *
30 * @brief Declares APIs for audio rendering.
31 *
32 * @since 1.0
33 * @version 1.0
34 */
35
36#ifndef AUDIO_RENDER_H
37#define AUDIO_RENDER_H
38
39#include "audio_types.h"
40#include "audio_control.h"
41#include "audio_attribute.h"
42#include "audio_scene.h"
43#include "audio_volume.h"
44
45namespace OHOS {
46
47/**
48 * @brief Provides capabilities for audio rendering, including controlling the rendering, setting audio attributes,
49 * scenes, and volume, obtaining hardware latency, and rendering audio frames.
50 *
51 * @see AudioControl
52 * @see AudioAttribute
53 * @see AudioScene
54 * @see AudioVolume
55 * @since 1.0
56 * @version 1.0
57 */
58struct AudioRender {
59    /**
60     * @brief Defines the audio control. For details, see {@link AudioControl}.
61     */
62    struct AudioControl control;
63    /**
64     * @brief Defines the audio attribute. For details, see {@link AudioAttribute}.
65     */
66    struct AudioAttribute attr;
67    /**
68     * @brief Defines the audio scene. For details, see {@link AudioScene}.
69     */
70    struct AudioScene scene;
71    /**
72     * @brief Defines audio volume. For details, see {@link AudioVolume}.
73     */
74    struct AudioVolume volume;
75
76    /**
77     * @brief Obtains the estimated latency of the audio device driver.
78     *
79     * @param render Indicates the pointer to the <b>AudioRender</b> object to operate.
80     * @param ms Indicates the pointer to the latency (in milliseconds) to be obtained.
81     * @return Returns <b>0</b> if the latency is obtained; returns a negative value otherwise.
82     */
83    int32_t (*GetLatency)(struct AudioRender *render, uint32_t *ms);
84
85    /**
86     * @brief Writes a frame of output data (downlink data) into the audio driver for rendering.
87     *
88     * @param render Indicates the pointer to the <b>AudioRender</b> object to operate.
89     * @param frame Indicates the pointer to the frame to write.
90     * @param requestBytes Indicates the size of the frame, in bytes.
91     * @param replyBytes Indicates the pointer to the actual length (in bytes) of the audio data to write.
92     * @return Returns <b>0</b> if the data is written successfully; returns a negative value otherwise.
93     */
94    int32_t (*RenderFrame)(struct AudioRender *render, const void *frame, uint64_t requestBytes, uint64_t *replyBytes);
95
96    /**
97     * @brief Obtains the last number of output audio frames.
98     *
99     * @param render Indicates the pointer to the <b>AudioRender</b> object to operate.
100     * @param frames Indicates the pointer to the last number of output audio frames.
101     * @param time Indicates the pointer to the timestamp associated with the frame.
102     * @return Returns <b>0</b> if the last number is obtained; returns a negative value otherwise.
103     * @see RenderFrame
104     */
105    int32_t (*GetRenderPosition)(struct AudioRender *render, uint64_t *frames, struct AudioTimeStamp *time);
106
107    /**
108     * @brief Sets the audio rendering speed.
109     *
110     * @param render Indicates the pointer to the <b>AudioRender</b> object to operate.
111     * @param speed Indicates the rendering speed to set.
112     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
113     * @see GetRenderSpeed
114     */
115    int32_t (*SetRenderSpeed)(struct AudioRender *render, float speed);
116
117    /**
118     * @brief Obtains the current audio rendering speed.
119     *
120     * @param render Indicates the pointer to the <b>AudioRender</b> object to operate.
121     * @param speed Indicates the pointer to the current rendering speed to obtain.
122     * @return Returns <b>0</b> if the speed is successfully obtained; returns a negative value otherwise.
123     * @see SetRenderSpeed
124     */
125    int32_t (*GetRenderSpeed)(struct AudioRender *render, float *speed);
126
127    /**
128     * @brief Sets the channel mode for audio rendering.
129     *
130     * @param render Indicates the pointer to the <b>AudioRender</b> object to operate.
131     * @param mode Indicates the channel mode to set.
132     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
133     * @see GetChannelMode
134     */
135    int32_t (*SetChannelMode)(struct AudioRender *render, enum AudioChannelMode mode);
136
137    /**
138     * @brief Obtains the current channel mode for audio rendering.
139     *
140     * @param render Indicates the pointer to the <b>AudioRender</b> object to operate.
141     * @param mode Indicates the pointer to the channel mode to obtain.
142     * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise.
143     * @see SetChannelMode
144     */
145    int32_t (*GetChannelMode)(struct AudioRender *render, enum AudioChannelMode *mode);
146
147    /**
148     * @brief Registers an audio callback that will be invoked during playback when buffer data writing or
149     * buffer drain is complete.
150     *
151     * @param render Indicates the pointer to the <b>AudioRender</b> object to operate.
152     * @param callback Indicates the callback to register.
153     * @param cookie Indicates the pointer to the callback parameters.
154     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
155     * @see RegCallback
156     */
157    int32_t (*RegCallback)(struct AudioRender *render, RenderCallback callback, void* cookie);
158
159    /**
160     * @brief Drains the buffer.
161     *
162     * @param render Indicates the pointer to the <b>AudioRender</b> object to operate.
163     * @param type Indicates the pointer to the execution type of this function. For details,
164     * see {@link AudioDrainNotifyType}.
165     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
166     * @see RegCallback
167     */
168    int32_t (*DrainBuffer)(struct AudioRender *render, enum AudioDrainNotifyType *type);
169
170    /**
171     * @brief query whether the vendor supports draining buffer
172     *
173     * @param render Indicates the pointer to the <b>AudioRender</b> object to operate.
174     * @param support indicates the state whether the vendor supports draining buffer. Value <b>true</b> means that
175     * the vendor supports, and <b>false</b> means the opposite.
176     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
177     * @see IsSupportsDrain
178     */
179    int32_t (*IsSupportsDrain)(struct AudioRender *render, bool *support);
180};
181} /* end of OHOS */
182#endif /* AUDIO_RENDER_H */
183/** @} */
184