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