1/*
2 * Copyright (c) 2020-2021 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_scene.h
29 *
30 * @brief Declares APIs for audio scenes.
31 *
32 * @since 1.0
33 * @version 1.0
34 */
35
36#ifndef AUDIO_SCENE_H
37#define AUDIO_SCENE_H
38
39#include "audio_types.h"
40
41/**
42 * @brief Provides scene-related APIs for audio rendering or capturing, including functions to
43 * select an audio scene and check whether the configuration of an audio scene is supported.
44 *
45 * @since 1.0
46 * @version 1.0
47 */
48struct AudioScene {
49    /**
50     * @brief Checks whether the configuration of an audio scene is supported.
51     *
52     * @param handle Indicates the audio handle.
53     * @param scene Indicates the pointer to the descriptor of the audio scene.
54     * @param supported Indicates the pointer to the variable specifying whether the configuration is supported.
55     * Value <b>true</b> means that the configuration is supported, and <b>false</b> means the opposite.
56     * @return Returns <b>0</b> if the result is obtained; returns a negative value otherwise.
57     * @see SelectScene
58     */
59    int32_t (*CheckSceneCapability)(AudioHandle handle, const struct AudioSceneDescriptor *scene, bool *supported);
60
61    /**
62     * @brief Selects an audio scene.
63     *
64     * <ul>
65     *   <li>To select a specific audio scene, you need to specify both the application scenario and output device.
66     *     For example, to select a scene using a smartphone speaker as the output device, set <b>scene</b> according
67     *     to the scenarios where the speaker is used. For example:</li>
68     *     <ul>
69     *       <li>For media playback, set the value to <b>media_speaker</b>.</li>
70     *       <li>For a voice call, set the value to <b>voice_speaker</b>.</li>
71     *     </ul>
72     *   <li>To select only the application scenario, such as media playback, movie, or gaming, you can set
73     *     <b>scene</b> to <b>media</b>, <b>movie</b>, or <b>game</b>, respectively.</li>
74     *   <li>To select only the output device, such as media receiver, speaker, or headset, you can set
75     *     <b>scene</b> to <b>receiver</b>, <b>speaker</b>, or <b>headset</b>, respectively.</li>
76     * </ul>
77     * @param handle Indicates the audio handle.
78     * @param scene Indicates the pointer to the descriptor of the audio scene to select.
79     * @return Returns <b>0</b> if the scene is selected successfully; returns a negative value otherwise.
80     * @see CheckSceneCapability
81     */
82    int32_t (*SelectScene)(AudioHandle handle, const struct AudioSceneDescriptor *scene);
83};
84
85#endif /* AUDIO_SCENE_H */
86/** @} */
87