1 /*
2  * Copyright 2021, The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *     http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /*
18  * structure defining the function pointers that system-side folks
19  * use to invoke operations within the MediaFormat shaping library
20  *
21  * This is the include file the outside world uses.
22  */
23 
24 #ifndef LIBMEDIAFORMATSHAPER_FORMATSHAPER_H_
25 #define LIBMEDIAFORMATSHAPER_FORMATSHAPER_H_
26 
27 namespace android {
28 namespace mediaformatshaper {
29 
30 /*
31  * An opaque handle clients use to refer to codec+mediatype being shaped.
32  */
33 typedef void (*shaperHandle_t);
34 
35 /*
36  * shapeFormat applies any re-shaping on the passed AMediaFormat.
37  * The updated format is returned in-place.
38  */
39 typedef int (*shapeFormat_t)(shaperHandle_t shaperHandle,
40                              AMediaFormat* inFormat, int flags);
41 
42 /*
43  * getMapping returns any mappings from standard keys to codec-specific keys.
44  * The return is a vector of const char* which are set up in pairs
45  * of "from", and "to".
46  * This array is always finished with a pair of nulls (to indicate a null from
47  * and a null to)
48  */
49 
50 typedef const char **(*getMappings_t)(shaperHandle_t shaperHandle, const char *kind);
51 
52 /*
53  * Returns a handle to the shaperHandle for the specified codec and mediatype.
54  * If none exists, it returns null.
55  */
56 typedef shaperHandle_t (*findShaper_t)(const char *codecName, const char *mediaType);
57 
58 /*
59  * Creates and returns an empty shaperHandle that the client can populate using the
60  * setFeature() and setMap() operations.
61  */
62 typedef shaperHandle_t (*createShaper_t)(const char *codecName, const char *mediaType);
63 
64 /*
65  * Registers the indicated shaperHandle for the indicated codec and mediatype.
66  * This call returns the shaperHandle that is to be used for further shaper operations.
67  * The returned value may be different than the one passed as an argument if another
68  * shaperinfo was registered while the passed one was being configured.
69  */
70 typedef shaperHandle_t (*registerShaper_t)(shaperHandle_t shaper, const char *codecName,
71                                          const char *mediaType);
72 
73 /*
74  * establishes a mapping between the standard key "from" and the codec-specific key "to"
75  * in the "kind" namespace. This mapping is specific to the indicated codecName when
76  * encoding for the indicated mediaType.
77  */
78 typedef int (*setMap_t)(shaperHandle_t shaper, const char *kind, const char *from, const char *to);
79 
80 /*
81  * establishes that codec "codecName" encoding for "mediaType" supports the indicated
82  * feature at the indicated value
83  */
84 typedef int (*setFeature_t)(shaperHandle_t shaper, const char *feature, int value);
85 
86 /*
87  * establishes that codec "codecName" encoding for "mediaType" supports the indicated
88  * tuning at the indicated value
89  */
90 typedef int (*setTuning_t)(shaperHandle_t shaper, const char *feature, const char * value);
91 
92 /*
93  * The expectation is that the client will implement a flow similar to the following when
94  * setting up an encoding.
95  *
96  * if ((shaper=formatShaperops->findShaper(codecName, mediaType)) == NULL) {
97  *     for (all codec features) {
98  *         get feature name, feature value
99  *         formatShaperops->setFeature(shaper,, featurename, featurevalue)
100  *     }
101  *     for (all codec mappings) {
102  *         get mapping 'kind', mapping 'from', mapping 'to'
103  *         formatShaperops->setMap(shaper, kind, from, to)
104  *     }
105  * }
106  *
107  */
108 
109 typedef struct FormatShaperOps {
110     const uint32_t version;
111 
112     /*
113      * find, create, setup, and register the shaper info
114      */
115     findShaper_t findShaper;
116     createShaper_t createShaper;
117     setMap_t setMap;
118     setFeature_t setFeature;
119     registerShaper_t registerShaper;
120 
121     /*
122      * use the shaper info
123      */
124     shapeFormat_t shapeFormat;
125     getMappings_t getMappings;
126     getMappings_t getReverseMappings;
127 
128     setTuning_t setTuning;
129 
130     // additions happen at the end of the structure
131 } FormatShaperOps_t;
132 
133 // versioninf information
134 const uint32_t SHAPER_VERSION_UNKNOWN = 0;
135 const uint32_t SHAPER_VERSION_V1 = 1;
136 
137 }  // namespace mediaformatshaper
138 }  // namespace android
139 
140 #endif  // LIBMEDIAFORMATSHAPER_FORMATSHAPER_H_
141