0006e2cebab5b65cc53948ee162f0ceaa26d3bf8
[platform/upstream/gstreamer.git] / gst / gstformat.c
1 /* GStreamer
2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3  *                    2000 Wim Taymans <wim.taymans@chello.be>
4  *                    2005 Wim Taymans <wim@fluendo.com>
5  *
6  * gstformat.c: GstFormat registration
7  *
8  * This library is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU Library General Public
10  * License as published by the Free Software Foundation; either
11  * version 2 of the License, or (at your option) any later version.
12  *
13  * This library is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16  * Library General Public License for more details.
17  *
18  * You should have received a copy of the GNU Library General Public
19  * License along with this library; if not, write to the
20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21  * Boston, MA 02111-1307, USA.
22  */
23
24 /**
25  * SECTION:gstformat
26  * @short_description: Dynamically register new data formats
27  * @see_also: #GstPad, #GstElement
28  *
29  * GstFormats functions are used to register a new format to the gstreamer
30  * core.  Formats can be used to perform seeking or conversions/query
31  * operations.
32  */
33
34
35 #include "gst_private.h"
36 #include <string.h>
37 #include "gstformat.h"
38 #include "gstenumtypes.h"
39
40 static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
41 static GList *_gst_formats = NULL;
42 static GHashTable *_nick_to_format = NULL;
43 static GHashTable *_format_to_nick = NULL;
44 static guint32 _n_values = 1;   /* we start from 1 because 0 reserved for UNDEFINED */
45
46 static GstFormatDefinition standard_definitions[] = {
47   {GST_FORMAT_DEFAULT, "default", "Default format for the media type", 0},
48   {GST_FORMAT_BYTES, "bytes", "Bytes", 0},
49   {GST_FORMAT_TIME, "time", "Time", 0},
50   {GST_FORMAT_BUFFERS, "buffers", "Buffers", 0},
51   {GST_FORMAT_PERCENT, "percent", "Percent", 0},
52   {0, NULL, NULL, 0}
53 };
54
55 void
56 _gst_format_initialize (void)
57 {
58   GstFormatDefinition *standards = standard_definitions;
59
60   g_static_mutex_lock (&mutex);
61   if (_nick_to_format == NULL) {
62     _nick_to_format = g_hash_table_new (g_str_hash, g_str_equal);
63     _format_to_nick = g_hash_table_new (NULL, NULL);
64   }
65
66   while (standards->nick) {
67     standards->quark = g_quark_from_static_string (standards->nick);
68     g_hash_table_insert (_nick_to_format, (gpointer) standards->nick,
69         standards);
70     g_hash_table_insert (_format_to_nick, GINT_TO_POINTER (standards->value),
71         standards);
72
73     _gst_formats = g_list_append (_gst_formats, standards);
74     standards++;
75     _n_values++;
76   }
77   /* getting the type registers the enum */
78   g_type_class_ref (gst_format_get_type ());
79   g_static_mutex_unlock (&mutex);
80 }
81
82 /**
83  * gst_format_get_name:
84  * @format: a #GstFormat
85  *
86  * Get a printable name for the given format. Do not modify or free.
87  *
88  * Returns: a reference to the static name of the format or NULL if
89  * the format is unknown.
90  */
91 const gchar *
92 gst_format_get_name (GstFormat format)
93 {
94   const GstFormatDefinition *def;
95   const gchar *result;
96
97   if ((def = gst_format_get_details (format)) != NULL)
98     result = def->nick;
99   else
100     result = NULL;
101
102   return result;
103 }
104
105 /**
106  * gst_format_to_quark:
107  * @format: a #GstFormat
108  *
109  * Get the unique quark for the given format.
110  *
111  * Returns: the quark associated with the format or 0 if the format
112  * is unknown.
113  */
114 GQuark
115 gst_format_to_quark (GstFormat format)
116 {
117   const GstFormatDefinition *def;
118   GQuark result;
119
120   if ((def = gst_format_get_details (format)) != NULL)
121     result = def->quark;
122   else
123     result = 0;
124
125   return result;
126 }
127
128 /**
129  * gst_format_register:
130  * @nick: The nick of the new format
131  * @description: The description of the new format
132  *
133  * Create a new GstFormat based on the nick or return an
134  * already registered format with that nick.
135  *
136  * Returns: A new GstFormat or an already registered format
137  * with the same nick.
138  *
139  * MT safe.
140  */
141 GstFormat
142 gst_format_register (const gchar * nick, const gchar * description)
143 {
144   GstFormatDefinition *format;
145   GstFormat query;
146
147   g_return_val_if_fail (nick != NULL, GST_FORMAT_UNDEFINED);
148   g_return_val_if_fail (description != NULL, GST_FORMAT_UNDEFINED);
149
150   query = gst_format_get_by_nick (nick);
151   if (query != GST_FORMAT_UNDEFINED)
152     return query;
153
154   g_static_mutex_lock (&mutex);
155   format = g_slice_new (GstFormatDefinition);
156   format->value = _n_values;
157   format->nick = g_strdup (nick);
158   format->description = g_strdup (description);
159   format->quark = g_quark_from_static_string (format->nick);
160
161   g_hash_table_insert (_nick_to_format, (gpointer) format->nick, format);
162   g_hash_table_insert (_format_to_nick, GINT_TO_POINTER (format->value),
163       format);
164   _gst_formats = g_list_append (_gst_formats, format);
165   _n_values++;
166   g_static_mutex_unlock (&mutex);
167
168   return format->value;
169 }
170
171 /**
172  * gst_format_get_by_nick:
173  * @nick: The nick of the format
174  *
175  * Return the format registered with the given nick.
176  *
177  * Returns: The format with @nick or GST_FORMAT_UNDEFINED
178  * if the format was not registered.
179  */
180 GstFormat
181 gst_format_get_by_nick (const gchar * nick)
182 {
183   GstFormatDefinition *format;
184
185   g_return_val_if_fail (nick != NULL, GST_FORMAT_UNDEFINED);
186
187   g_static_mutex_lock (&mutex);
188   format = g_hash_table_lookup (_nick_to_format, nick);
189   g_static_mutex_unlock (&mutex);
190
191   if (format != NULL)
192     return format->value;
193   else
194     return GST_FORMAT_UNDEFINED;
195 }
196
197 /**
198  * gst_formats_contains:
199  * @formats: The format array to search
200  * @format: the format to find
201  *
202  * See if the given format is inside the format array.
203  *
204  * Returns: TRUE if the format is found inside the array
205  */
206 gboolean
207 gst_formats_contains (const GstFormat * formats, GstFormat format)
208 {
209   if (!formats)
210     return FALSE;
211
212   while (*formats) {
213     if (*formats == format)
214       return TRUE;
215
216     formats++;
217   }
218   return FALSE;
219 }
220
221
222 /**
223  * gst_format_get_details:
224  * @format: The format to get details of
225  *
226  * Get details about the given format.
227  *
228  * Returns: The #GstFormatDefinition for @format or NULL on failure.
229  *
230  * MT safe.
231  */
232 const GstFormatDefinition *
233 gst_format_get_details (GstFormat format)
234 {
235   const GstFormatDefinition *result;
236
237   g_static_mutex_lock (&mutex);
238   result = g_hash_table_lookup (_format_to_nick, GINT_TO_POINTER (format));
239   g_static_mutex_unlock (&mutex);
240
241   return result;
242 }
243
244 /**
245  * gst_format_iterate_definitions:
246  *
247  * Iterate all the registered formats. The format definition is read
248  * only.
249  *
250  * Returns: (transfer full): a GstIterator of #GstFormatDefinition.
251  */
252 GstIterator *
253 gst_format_iterate_definitions (void)
254 {
255   GstIterator *result;
256
257   g_static_mutex_lock (&mutex);
258   /* FIXME: register a boxed type for GstFormatDefinition */
259   result = gst_iterator_new_list (G_TYPE_POINTER,
260       g_static_mutex_get_mutex (&mutex), &_n_values, &_gst_formats, NULL, NULL);
261   g_static_mutex_unlock (&mutex);
262
263   return result;
264 }