Gitiles
Code Review Sign In
review.evervolv.com / android_frameworks_av / c282e3eee921453fc9188705b4879d6289b71f9c / . / include / media / EffectFactoryApi.h
blob: 8179c234d339c90009d50755299a281664f93a07 [file] [log] [blame]
Eric Laurent135ad072010-05-21 06:05:13 -0700[diff] [blame]1/*
2 * Copyright (C) 2010 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#ifndef ANDROID_EFFECTFACTORYAPI_H_
18#define ANDROID_EFFECTFACTORYAPI_H_
19
20#include <errno.h>
21#include <stdint.h>
22#include <sys/types.h>
23#include <media/EffectApi.h>
24
25#if __cplusplus
26extern "C" {
27#endif
28
29/////////////////////////////////////////////////
30// Effect factory interface
31/////////////////////////////////////////////////
32
33////////////////////////////////////////////////////////////////////////////////
34//
35// Function: EffectQueryNumberEffects
36//
37// Description: Returns the number of different effect in all loaded libraries.
38// Each effect must have a different effect uuid (see
39// effect_descriptor_t). This function together with EffectQueryNext()
40// is used to enumerate all effects present in all loaded libraries.
41// Each time EffectQueryNumberEffects() is called, the factory must
42// reset the index of the effect descriptor returned by next call to
43// EffectQueryNext() to restart enumeration from the beginning.
44//
45// Input/Output:
46// pNumEffects: address where the number of effects should be returned.
47//
48// Output:
49// returned value: 0 successful operation.
50// -ENODEV factory failed to initialize
51// -EINVAL invalid pNumEffects
52// *pNumEffects: updated with number of effects in factory
53//
54////////////////////////////////////////////////////////////////////////////////
55int EffectQueryNumberEffects(int *pNumEffects);
56
57////////////////////////////////////////////////////////////////////////////////
58//
59// Function: EffectQueryNext
60//
61// Description: Returns a descriptor of the next available effect.
62// See effect_descriptor_t for a details on effect descriptor.
63// This function together with EffectQueryNext() is used to enumerate all
64// effects present in all loaded libraries. The enumeration sequence is:
65// EffectQueryNumberEffects(&num_effects);
66// while (num_effects--)
67// EffectQueryNext();
68//
69// Input/Output:
70// pDescriptor: address where to return the effect descriptor.
71//
72// Output:
73// returned value: 0 successful operation.
74// -ENODEV factory failed to initialize
75// -EINVAL invalid pDescriptor
76// -ENOENT no more effect available
77// *pDescriptor: updated with the effect descriptor.
78//
79////////////////////////////////////////////////////////////////////////////////
80int EffectQueryNext(effect_descriptor_t *pDescriptor);
81
82////////////////////////////////////////////////////////////////////////////////
83//
84// Function: EffectCreate
85//
86// Description: Creates an effect engine of the specified type and returns an
87// effect control interface on this engine. The function will allocate the
88// resources for an instance of the requested effect engine and return
89// a handler on the effect control interface.
90//
91// Input:
92// pEffectUuid: pointer to the effect uuid.
93//
94// Input/Output:
95// pInterface: address where to return the effect interface.
96//
97// Output:
98// returned value: 0 successful operation.
99// -ENODEV factory failed to initialize
100// -EINVAL invalid pEffectUuid or pInterface
101// -ENOENT No effect with this uuid found
102// *pInterface: updated with the effect interface.
103//
104////////////////////////////////////////////////////////////////////////////////
105int EffectCreate(effect_uuid_t *pEffectUuid, effect_interface_t *pInterface);
106
107////////////////////////////////////////////////////////////////////////////////
108//
109// Function: EffectRelease
110//
111// Description: Releases the effect engine whose handler is given as argument.
112// All resources allocated to this particular instance of the effect are
113// released.
114//
115// Input:
116// interface: handler on the effect interface to be released.
117//
118// Output:
119// returned value: 0 successful operation.
120// -ENODEV factory failed to initialize
121// -EINVAL invalid interface handler
122//
123////////////////////////////////////////////////////////////////////////////////
124int EffectRelease(effect_interface_t interface);
125
126////////////////////////////////////////////////////////////////////////////////
127//
128// Function: EffectLoadLibrary
129//
130// Description: Loads the effect library which path is given as first argument.
131// This must be the full path of a dynamic library (.so) implementing one or
132// more effect engines and exposing the effect library interface described in
133// EffectApi.h. The function returns a handle on the library for used by
134// further call to EffectUnloadLibrary() to unload the library.
135//
136// Input:
137// libPath: full path of the dynamic library file in the file system.
138//
139// handle: address where to return the library handle
140//
141// Output:
142// returned value: 0 successful operation.
143// -ENODEV Effect factory not initialized or
144// library could not be loaded or
145// library does not implement required functions
146// -EINVAL invalid libPath string or handle
147//
148////////////////////////////////////////////////////////////////////////////////
149int EffectLoadLibrary(const char *libPath, int *handle);
150
151////////////////////////////////////////////////////////////////////////////////
152//
153// Function: EffectUnloadLibrary
154//
155// Description: Unloads the effect library which handle is given as argument.
156//
157// Input:
158// handle: library handle
159//
160// Output:
161// returned value: 0 successful operation.
162// -ENODEV Effect factory not initialized
163// -ENOENT invalid handle
164//
165////////////////////////////////////////////////////////////////////////////////
166int EffectUnloadLibrary(int handle);
167
168
169
170////////////////////////////////////////////////////////////////////////////////
171//
172// Function: EffectGetDescriptor
173//
174// Description: Returns the descriptor of the effect which uuid is pointed
175// to by first argument.
176//
177// Input:
178// pEffectUuid: pointer to the effect uuid.
179//
180// Input/Output:
181// pDescriptor: address where to return the effect descriptor.
182//
183// Output:
184// returned value: 0 successful operation.
185// -ENODEV factory failed to initialize
186// -EINVAL invalid pEffectUuid or pDescriptor
187// -ENOENT No effect with this uuid found
188// *pDescriptor: updated with the effect descriptor.
189//
190////////////////////////////////////////////////////////////////////////////////
191int EffectGetDescriptor(effect_uuid_t *pEffectUuid, effect_descriptor_t *pDescriptor);
192
193////////////////////////////////////////////////////////////////////////////////
194//
195// Function: EffectIsNullUuid
196//
197// Description: Helper function to compare effect uuid to EFFECT_UUID_NULL
198//
199// Input:
200// pEffectUuid: pointer to effect uuid to compare to EFFECT_UUID_NULL.
201//
202// Output:
203// returned value: 0 if uuid is different from EFFECT_UUID_NULL.
204// 1 if uuid is equal to EFFECT_UUID_NULL.
205//
206////////////////////////////////////////////////////////////////////////////////
207int EffectIsNullUuid(effect_uuid_t *pEffectUuid);
208
209#if __cplusplus
210} // extern "C"
211#endif
212
213
214#endif /*ANDROID_EFFECTFACTORYAPI_H_*/