1 /*
2  * Copyright (c) 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 feature_processor
18  * @{
19  *
20  * @brief Defines the basic functions for FeatureProcessor, including the supported data types
21  * and other related configuration parameters.
22  *
23  * @since 2.2
24  * @version 1.0
25  */
26 
27 /**
28  * @file feature_processor.h
29  *
30  * @brief Defines basic functions for FeatureProcessor, including the supported data types
31  * and other related configuration paramters.
32  *
33  * @since 2.2
34  * @version 1.0
35  */
36 
37 #ifndef AUDIO_PREPROCESS_FEATURE_PROCESSOR_H
38 #define AUDIO_PREPROCESS_FEATURE_PROCESSOR_H
39 
40 #include <cstdint>
41 #include <string>
42 
43 namespace OHOS {
44 namespace AI {
45 namespace Feature {
46 /**
47  *
48  * @brief Defines the maximum number of channels for the frequency-domain features generated by FeatureProcessor.
49  *
50  * @since 2.2
51  * @version 1.0
52  */
53 #define MAX_NUM_CHANNELS 100
54 
55 /**
56  *
57  * @brief Defines the maximum number of samples supported by FeatureProcessor.
58  *
59  * @since 2.2
60  * @version 1.0
61  */
62 #define MAX_SAMPLE_SIZE 20000
63 
64 /**
65  *
66  * @brief Defines the number of bytes based on the data type.
67  *
68  * @since 2.2
69  * @version 1.0
70  */
71 #define CONVERT_DATATYPE_TO_SIZE(x) static_cast<uint8_t>((x) & 7)
72 
73 /**
74  *
75  * @brief Defines the data structures supported by FeatureProcessor.
76  *
77  * @since 2.2
78  * @version 1.0
79  */
80 enum DataType {
81     UINT8  = 1,
82     UINT16 = 2,
83     UINT32 = 4,
84     INT8   = 1 | (1 << 3),
85     INT16  = 2 | (1 << 3),
86     INT32  = 4 | (1 << 3),
87     FLOAT  = 4 | (1 << 4),
88     UNKNOWN,
89 };
90 
91 /**
92  *
93  * @brief Specifies the structure for the FeatureProcessor configuration.
94  *
95  * @since 2.2
96  * @version 1.0
97  */
98 struct FeatureProcessorConfig {
99     /** Data types supported by FeatureProcessor. For details, see {@link DataType}. */
100     DataType dataType = UNKNOWN;
101 };
102 
103 /**
104  *
105  * @brief Defines the basic structure for the data to be processed by FeatureProcessor.
106  *
107  * @since 2.2
108  * @version 1.0
109  */
110 struct FeatureData {
111     /** Type of feature data. For details, see {@link DataType}. */
112     DataType dataType;
113     /** Start address of feature data */
114     void *data;
115     /** Length of feature data */
116     size_t size;
117 };
118 
119 /**
120  *
121  * @brief Defines basic functions for FeatureProcessor.
122  *
123  * @since 2.2
124  * @version 1.0
125  */
126 class FeatureProcessor {
127 public:
128     /**
129      * @brief Defines the destructor for FeatureProcessor.
130      *
131      * @since 2.2
132      * @version 1.0
133      */
134     virtual ~FeatureProcessor() = default;
135 
136     /**
137      * @brief Initializes FeatureProcessor.
138      *
139      * @param config Indicates the pointer to the basic configuration of FeatureProcessor.
140      * The caller needs to pass in a pointer address defined by {@link FeatureProcessorConfig}
141      * and release the pointer after using it.
142      * @return Returns {@link RETCODE_SUCCESS} if the operation is successful;
143      * returns {@link RETCODE_FAILURE} otherwise.
144      *
145      * @since 2.2
146      * @version 1.0
147      */
148     virtual int32_t Init(const FeatureProcessorConfig *config) = 0;
149 
150     /**
151      * @brief Performs feature processing.
152      *
153      * @param input Indicates the input data for FeatureProcessor. The caller must pass in FeatureData
154      * of the type defined by {@link DataType}.
155      * @param output Indicates the output data for FeatureProcessor. The caller must pass in FeatureData
156      * of the type defined by {@link DataType}. If and only if its address is empty and the data length is <b>0</b>,
157      * data will be filled by the FeatureProcessor.
158      * @return Returns {@link RETCODE_SUCCESS} if the operation is successful;
159      * returns {@link RETCODE_FAILURE} otherwise.
160      *
161      * @since 2.2
162      * @version 1.0
163      */
164     virtual int32_t Process(const FeatureData &input, FeatureData &output) = 0;
165 
166     /**
167      * @brief Releases resources.
168      *
169      * @since 2.2
170      * @version 1.0
171      */
172     virtual void Release() = 0;
173 };
174 } // namespace Feature
175 } // namespace AI
176 } // namespace OHOS
177 #endif // AUDIO_PREPROCESS_FEATURE_PROCESSOR_H
178 /** @} */