configure: fetch a specific revision of FFmpeg.
[vaapi:challenzhous-mplayer.git] / m_property.h
1 /*
2  * This file is part of MPlayer.
3  *
4  * MPlayer is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU General Public License as published by
6  * the Free Software Foundation; either version 2 of the License, or
7  * (at your option) any later version.
8  *
9  * MPlayer is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License along
15  * with MPlayer; if not, write to the Free Software Foundation, Inc.,
16  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
17  */
18
19 #ifndef MPLAYER_M_PROPERTY_H
20 #define MPLAYER_M_PROPERTY_H
21
22 #include "m_option.h"
23
24 /// \defgroup properties Properties
25 ///
26 /// Properties provide an interface to query and set the state of various
27 /// things in MPlayer. The API is based on the \ref Options API like the
28 /// \ref Config, but instead of using variables, properties use an ioctl like
29 /// function. The function is used to perform various actions like get and set
30 /// (see \ref PropertyActions).
31 ///@{
32
33 /// \file
34
35 /// \defgroup PropertyActions Property actions
36 /// \ingroup Properties
37 ///@{
38
39 /// Get the current value.
40 /** \param arg Pointer to a variable of the right type.
41  */
42 #define M_PROPERTY_GET         0
43
44 /// Get a string representing the current value.
45 /** Set the variable to a newly allocated string or NULL.
46  *  \param arg Pointer to a char* variable.
47  */
48 #define M_PROPERTY_PRINT       1
49
50 /// Set a new value.
51 /** The variable is updated to the value actually set.
52  *  \param arg Pointer to a variable of the right type.
53  */
54 #define M_PROPERTY_SET         2
55
56 /// Set a new value from a string.
57 /** \param arg String containing the value.
58  */
59 #define M_PROPERTY_PARSE       3
60
61 /// Increment the current value.
62 /** The sign of the argument is also taken into account if applicable.
63  *  \param arg Pointer to a variable of the right type or NULL.
64  */
65 #define M_PROPERTY_STEP_UP     4
66
67 /// Decrement the current value.
68 /** The sign of the argument is also taken into account if applicable.
69  *  \param arg Pointer to a variable of the right type or NULL.
70  */
71 #define M_PROPERTY_STEP_DOWN   5
72
73 /// Get a string containg a parsable representation.
74 /** Set the variable to a newly allocated string or NULL.
75  *  \param arg Pointer to a char* variable.
76  */
77 #define M_PROPERTY_TO_STRING   6
78
79 /// Pass down an action to a sub-property.
80 #define M_PROPERTY_KEY_ACTION  7
81
82 /// Get a m_option describing the property.
83 #define M_PROPERTY_GET_TYPE    8
84
85 ///@}
86
87 /// \defgroup PropertyActionsArg Property actions argument type
88 /// \ingroup Properties
89 /// \brief  Types used as action argument.
90 ///@{
91
92 /// Argument for \ref M_PROPERTY_KEY_ACTION
93 typedef struct {
94     const char* key;
95     int action;
96     void* arg;
97 } m_property_action_t;
98
99 ///@}
100
101 /// \defgroup PropertyActionsReturn Property actions return code
102 /// \ingroup Properties
103 /// \brief  Return values for the control function.
104 ///@{
105
106 /// Returned on success.
107 #define M_PROPERTY_OK                1
108
109 /// Returned on error.
110 #define M_PROPERTY_ERROR             0
111
112 /// \brief Returned when the property can't be used, for example something about
113 /// the subs while playing audio only
114 #define M_PROPERTY_UNAVAILABLE      -1
115
116 /// Returned if the requested action is not implemented.
117 #define M_PROPERTY_NOT_IMPLEMENTED  -2
118
119 /// Returned when asking for a property that doesn't exist.
120 #define M_PROPERTY_UNKNOWN          -3
121
122 /// Returned when the action can't be done (like setting the volume when edl mute).
123 #define M_PROPERTY_DISABLED         -4
124
125 ///@}
126
127 /// \ingroup Properties
128 /// \brief Property action callback.
129 typedef int(*m_property_ctrl_f)(const m_option_t* prop,int action,void* arg,void *ctx);
130
131 /// Do an action on a property.
132 /** \param prop_list The list of properties.
133  *  \param prop The path of the property.
134  *  \param action See \ref PropertyActions.
135  *  \param arg Argument, usually a pointer to the data type used by the property.
136  *  \return See \ref PropertyActionsReturn.
137  */
138 int m_property_do(const m_option_t* prop_list, const char* prop,
139                   int action, void* arg, void *ctx);
140
141 /// Print a list of properties.
142 void m_properties_print_help_list(const m_option_t* list);
143
144 /// Expand a property string.
145 /** This function allows to print strings containing property values.
146  *  ${NAME} is expanded to the value of property NAME or an empty
147  *  string in case of error. $(NAME:STR) expand STR only if the property
148  *  NAME is available.
149  *
150  *  \param prop_list An array of \ref m_option describing the available
151  *                   properties.
152  *  \param str The string to expand.
153  *  \return The newly allocated expanded string.
154  */
155 char* m_properties_expand_string(const m_option_t* prop_list,char* str, void *ctx);
156
157 // Helpers to use MPlayer's properties
158
159 /// Do an action with an MPlayer property.
160 int mp_property_do(const char* name,int action, void* val, void *ctx);
161
162 /// Get the value of a property as a string suitable for display in an UI.
163 char* mp_property_print(const char *name, void* ctx);
164
165 /// \defgroup PropertyImplHelper Property implementation helpers
166 /// \ingroup Properties
167 /// \brief Helper functions for common property types.
168 ///@{
169
170 /// Clamp a value according to \ref m_option::min and \ref m_option::max.
171 #define M_PROPERTY_CLAMP(prop,val) do {                                 \
172         if(((prop)->flags & M_OPT_MIN) && (val) < (prop)->min)          \
173             (val) = (prop)->min;                                        \
174         else if(((prop)->flags & M_OPT_MAX) && (val) > (prop)->max)     \
175             (val) = (prop)->max;                                        \
176     } while(0)
177
178 /// Implement get.
179 int m_property_int_ro(const m_option_t* prop,int action,
180                       void* arg,int var);
181
182 /// Implement set, get and step up/down.
183 int m_property_int_range(const m_option_t* prop,int action,
184                          void* arg,int* var);
185
186 /// Same as m_property_int_range but cycle.
187 int m_property_choice(const m_option_t* prop,int action,
188                       void* arg,int* var);
189
190 int m_property_flag_ro(const m_option_t* prop,int action,
191                     void* arg,int var);
192
193 /// Switch betwen min and max.
194 int m_property_flag(const m_option_t* prop,int action,
195                     void* arg,int* var);
196
197 /// Implement get, print.
198 int m_property_float_ro(const m_option_t* prop,int action,
199                         void* arg,float var);
200
201 /// Implement set, get and step up/down
202 int m_property_float_range(const m_option_t* prop,int action,
203                            void* arg,float* var);
204
205 /// float with a print function which print the time in ms
206 int m_property_delay(const m_option_t* prop,int action,
207                      void* arg,float* var);
208
209 /// Implement get, print
210 int m_property_double_ro(const m_option_t* prop,int action,
211                          void* arg,double var);
212
213 /// Implement print
214 int m_property_time_ro(const m_option_t* prop,int action,
215                        void* arg,double var);
216
217 /// get/print the string
218 int m_property_string_ro(const m_option_t* prop,int action,void* arg, char* str);
219
220 /// get/print a bitrate
221 int m_property_bitrate(const m_option_t* prop,int action,void* arg,int rate);
222
223 ///@}
224
225 ///@}
226
227 #endif /* MPLAYER_M_PROPERTY_H */