gstelementfactory.h 12.8 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
/* GStreamer
 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
 *               2000,2004 Wim Taymans <wim@fluendo.com>
 *
 * gstelement.h: Header for GstElement
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */


#ifndef __GST_ELEMENT_FACTORY_H__
#define __GST_ELEMENT_FACTORY_H__

Wim Taymans's avatar
Wim Taymans committed
27 28 29
typedef struct _GstElementFactory GstElementFactory;
typedef struct _GstElementFactoryClass GstElementFactoryClass;

30 31 32 33 34 35 36 37 38
#include <gst/gstconfig.h>
#include <gst/gstelement.h>
#include <gst/gstobject.h>
#include <gst/gstplugin.h>
#include <gst/gstpluginfeature.h>
#include <gst/gstiterator.h>

G_BEGIN_DECLS

39 40 41 42
/* FIXME 0.11: Move GstElementDetails into a private header and use it internally
 * in GstElementFactory, GstElementClass and the registry
 */

Wim Taymans's avatar
Wim Taymans committed
43 44
typedef struct _GstElementDetails GstElementDetails;

45 46 47
/**
 * GstElementDetails:
 * @longname: long, english name
48 49 50
 * @klass: string describing the type of element, as an unordered list
 * separated with slashes ('/'). See draft-klass.txt of the design docs
 * for more details and common types
51 52 53 54 55
 * @description: what the element is about
 * @author: who wrote this thing?
 *
 * This struct defines the public information about a #GstElement. It contains
 * meta-data about the element that is mostly for the benefit of editors.
56
 *
Wim Taymans's avatar
Wim Taymans committed
57
 * The @klass member can be used by applications to filter elements based
58
 * on functionality.
59
 */
60 61 62 63
/* FIXME: need translatable stuff in here (how handle in registry)?
 * can't we use _N("long name") in element implementations and use _(longname)
 * in gst_element_factory_get_longname()
 */
64 65 66
struct _GstElementDetails
{
  /*< public > */
67 68 69 70
  gchar *longname;
  gchar *klass;
  gchar *description;
  gchar *author;
71

72
  /*< private >*/
73 74 75
  gpointer _gst_reserved[GST_PADDING];
};

76 77 78
/**
 * GST_ELEMENT_DETAILS:
 * @longname: long, english name
79 80 81
 * @klass: string describing the type of element, as an unordered list
 * separated with slashes ('/'). See draft-klass.txt of the design docs
 * for more details and common types
82
 * @description: what the element is about
83
 * @author: who wrote this element
84 85 86
 *
 * Macro to initialize #GstElementDetails.
 */
Wim Taymans's avatar
Wim Taymans committed
87
#define GST_ELEMENT_DETAILS(longname,klass,description,author)          \
88
  { longname, klass, description, author, {NULL} }
89 90 91 92 93 94 95 96

/**
 * GST_IS_ELEMENT_DETAILS:
 * @details: the #GstElementDetails to check
 *
 * Tests if element details are initialized.
 */
/* FIXME: what about adding '&& (*__gst_reserved==NULL)' */
Wim Taymans's avatar
Wim Taymans committed
97 98
#define GST_IS_ELEMENT_DETAILS(details) (                                       \
  (details) && ((details)->longname != NULL) && ((details)->klass != NULL)      \
99 100
  && ((details)->description != NULL) && ((details)->author != NULL))

Wim Taymans's avatar
Wim Taymans committed
101 102 103 104 105 106 107
#define GST_TYPE_ELEMENT_FACTORY                (gst_element_factory_get_type())
#define GST_ELEMENT_FACTORY(obj)                (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_ELEMENT_FACTORY,\
                                                 GstElementFactory))
#define GST_ELEMENT_FACTORY_CLASS(klass)        (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_ELEMENT_FACTORY,\
                                                 GstElementFactoryClass))
#define GST_IS_ELEMENT_FACTORY(obj)             (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_ELEMENT_FACTORY))
#define GST_IS_ELEMENT_FACTORY_CLASS(klass)     (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_ELEMENT_FACTORY))
108
#define GST_ELEMENT_FACTORY_CAST(obj)           ((GstElementFactory *)(obj))
109

Wim Taymans's avatar
Wim Taymans committed
110 111 112 113 114
/**
 * GstElementFactory:
 *
 * The opaque #GstElementFactory data structure.
 */
115
struct _GstElementFactory {
Wim Taymans's avatar
Wim Taymans committed
116
  GstPluginFeature      parent;
117

Wim Taymans's avatar
Wim Taymans committed
118
  GType                 type;                   /* unique GType of element or 0 if not loaded */
119

120
  /* FIXME-0.11: deprecate this in favour of meta_data */
Wim Taymans's avatar
Wim Taymans committed
121
  GstElementDetails     details;
122

123
  GList *               staticpadtemplates;     /* GstStaticPadTemplate list */
Wim Taymans's avatar
Wim Taymans committed
124
  guint                 numpadtemplates;
125 126

  /* URI interface stuff */
Wim Taymans's avatar
Wim Taymans committed
127 128
  guint                 uri_type;
  gchar **              uri_protocols;
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
129

130
  GList *               interfaces;             /* interface type names this element implements */
131

132 133 134 135
  /*< private >*/
  /* FIXME-0.11: move up and replace details */
  gpointer		meta_data;
  gpointer _gst_reserved[GST_PADDING - 1];
136 137 138 139 140 141 142 143
};

struct _GstElementFactoryClass {
  GstPluginFeatureClass parent_class;

  gpointer _gst_reserved[GST_PADDING];
};

Wim Taymans's avatar
Wim Taymans committed
144
GType                   gst_element_factory_get_type            (void);
145

Wim Taymans's avatar
Wim Taymans committed
146
GstElementFactory *     gst_element_factory_find                (const gchar *name);
147

Wim Taymans's avatar
Wim Taymans committed
148
GType                   gst_element_factory_get_element_type    (GstElementFactory *factory);
149 150 151 152 153 154
const gchar *           gst_element_factory_get_longname        (GstElementFactory *factory);
const gchar *           gst_element_factory_get_klass           (GstElementFactory *factory);
const gchar *           gst_element_factory_get_description     (GstElementFactory *factory);
const gchar *           gst_element_factory_get_author          (GstElementFactory *factory);
const gchar *           gst_element_factory_get_documentation_uri (GstElementFactory *factory);
const gchar *           gst_element_factory_get_icon_name       (GstElementFactory *factory);
Wim Taymans's avatar
Wim Taymans committed
155
guint                   gst_element_factory_get_num_pad_templates (GstElementFactory *factory);
156
const GList *           gst_element_factory_get_static_pad_templates (GstElementFactory *factory);
Wim Taymans's avatar
Wim Taymans committed
157 158 159
gint                    gst_element_factory_get_uri_type        (GstElementFactory *factory);
gchar **                gst_element_factory_get_uri_protocols   (GstElementFactory *factory);
gboolean                gst_element_factory_has_interface       (GstElementFactory *factory,
160
                                                                 const gchar *interfacename);
161

Wim Taymans's avatar
Wim Taymans committed
162
GstElement*             gst_element_factory_create              (GstElementFactory *factory,
163 164
                                                                 const gchar *name) G_GNUC_MALLOC;
GstElement*             gst_element_factory_make                (const gchar *factoryname, const gchar *name) G_GNUC_MALLOC;
165

166
/* FIXME 0.11: move these two into our private headers */
167 168 169 170
void                    __gst_element_factory_add_static_pad_template (GstElementFactory *elementfactory,
                                                                 GstStaticPadTemplate *templ);
void                    __gst_element_factory_add_interface     (GstElementFactory *elementfactory,
                                                                 const gchar *interfacename);
Wim Taymans's avatar
Wim Taymans committed
171 172
gboolean                gst_element_register                    (GstPlugin *plugin, const gchar *name,
                                                                 guint rank, GType type);
173

174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226
/* Factory list functions */

/**
 * GstFactoryListType:
 * @GST_ELEMENT_FACTORY_TYPE_DECODER: Decoder elements
 * @GST_ELEMENT_FACTORY_TYPE_ENCODER: Encoder elements
 * @GST_ELEMENT_FACTORY_TYPE_SINK: Sink elements
 * @GST_ELEMENT_FACTORY_TYPE_SRC: Source elements
 * @GST_ELEMENT_FACTORY_TYPE_MUXER: Muxer elements
 * @GST_ELEMENT_FACTORY_TYPE_DEMUXER: Demuxer elements
 * @GST_ELEMENT_FACTORY_TYPE_PARSER: Parser elements
 * @GST_ELEMENT_FACTORY_TYPE_PAYLOADER: Payloader elements
 * @GST_ELEMENT_FACTORY_TYPE_DEPAYLOADER: Depayloader elements
 * @GST_ELEMENT_FACTORY_TYPE_MAX_ELEMENTS: Private, do not use
 * @GST_ELEMENT_FACTORY_TYPE_MEDIA_VIDEO: Elements handling video media types
 * @GST_ELEMENT_FACTORY_TYPE_MEDIA_AUDIO: Elements handling audio media types
 * @GST_ELEMENT_FACTORY_TYPE_MEDIA_IMAGE: Elements handling image media types
 * @GST_ELEMENT_FACTORY_TYPE_MEDIA_SUBTITLE: Elements handling subtitle media types
 * @GST_ELEMENT_FACTORY_TYPE_MEDIA_METADATA: Elements handling metadata media types
 *
 * The type of #GstElementFactory to filter.
 *
 * All @GstFactoryListType up to @GST_ELEMENT_FACTORY_TYPE_MAX_ELEMENTS are exclusive.
 *
 * If one or more of the MEDIA types are specified, then only elements
 * matching the specified media types will be selected.
 *
 * Since: 0.10.31
 */

typedef guint64 GstElementFactoryListType;

#define  GST_ELEMENT_FACTORY_TYPE_DECODER        (G_GUINT64_CONSTANT (1) << 0)
#define  GST_ELEMENT_FACTORY_TYPE_ENCODER        (G_GUINT64_CONSTANT (1) << 1)
#define  GST_ELEMENT_FACTORY_TYPE_SINK           (G_GUINT64_CONSTANT (1) << 2)
#define  GST_ELEMENT_FACTORY_TYPE_SRC            (G_GUINT64_CONSTANT (1) << 3)
#define  GST_ELEMENT_FACTORY_TYPE_MUXER          (G_GUINT64_CONSTANT (1) << 4)
#define  GST_ELEMENT_FACTORY_TYPE_DEMUXER        (G_GUINT64_CONSTANT (1) << 5)
#define  GST_ELEMENT_FACTORY_TYPE_PARSER         (G_GUINT64_CONSTANT (1) << 6)
#define  GST_ELEMENT_FACTORY_TYPE_PAYLOADER      (G_GUINT64_CONSTANT (1) << 7)
#define  GST_ELEMENT_FACTORY_TYPE_DEPAYLOADER    (G_GUINT64_CONSTANT (1) << 8)
#define  GST_ELEMENT_FACTORY_TYPE_FORMATTER      (G_GUINT64_CONSTANT (1) << 9)

#define  GST_ELEMENT_FACTORY_TYPE_MAX_ELEMENTS   (G_GUINT64_CONSTANT (1) << 48)

#define  GST_ELEMENT_FACTORY_TYPE_MEDIA_VIDEO    (G_GUINT64_CONSTANT (1) << 49)
#define  GST_ELEMENT_FACTORY_TYPE_MEDIA_AUDIO    (G_GUINT64_CONSTANT (1) << 50)
#define  GST_ELEMENT_FACTORY_TYPE_MEDIA_IMAGE    (G_GUINT64_CONSTANT (1) << 51)
#define  GST_ELEMENT_FACTORY_TYPE_MEDIA_SUBTITLE (G_GUINT64_CONSTANT (1) << 52)
#define  GST_ELEMENT_FACTORY_TYPE_MEDIA_METADATA (G_GUINT64_CONSTANT (1) << 53)

/**
 * GST_ELEMENT_FACTORY_TYPE_ANY:
227
 *
228 229 230 231
 * Elements of any of the defined GST_ELEMENT_FACTORY_LIST types
 *
 * Since: 0.10.31
 */
232
#define  GST_ELEMENT_FACTORY_TYPE_ANY ((G_GUINT64_CONSTANT (1) << 49) - 1)
233 234 235

/**
 * GST_ELEMENT_FACTORY_TYPE_MEDIA_ANY:
236
 *
237 238 239 240 241 242 243 244 245 246 247 248
 * Elements matching any of the defined GST_ELEMENT_FACTORY_TYPE_MEDIA types
 *
 * Note: Do not use this if you wish to not filter against any of the defined
 * media types. If you wish to do this, simply don't specify any 
 * GST_ELEMENT_FACTORY_TYPE_MEDIA flag.
 *
 * Since: 0.10.31
 */
#define GST_ELEMENT_FACTORY_TYPE_MEDIA_ANY (~G_GUINT64_CONSTANT (0) << 48)

/**
 * GST_ELEMENT_FACTORY_TYPE_VIDEO_ENCODER:
249
 *
250 251 252 253 254 255 256 257
 * All encoders handling video or image media types
 *
 * Since: 0.10.31
 */
#define GST_ELEMENT_FACTORY_TYPE_VIDEO_ENCODER (GST_ELEMENT_FACTORY_TYPE_ENCODER | GST_ELEMENT_FACTORY_TYPE_MEDIA_VIDEO | GST_ELEMENT_FACTORY_TYPE_MEDIA_IMAGE)

/**
 * GST_ELEMENT_FACTORY_TYPE_AUDIO_ENCODER:
258
 *
259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305
 * All encoders handling audio media types
 *
 * Since: 0.10.31
 */
#define GST_ELEMENT_FACTORY_TYPE_AUDIO_ENCODER (GST_ELEMENT_FACTORY_TYPE_ENCODER | GST_ELEMENT_FACTORY_TYPE_MEDIA_AUDIO)

/**
 * GST_ELEMENT_FACTORY_TYPE_AUDIOVIDEO_SINKS:
 *
 * All sinks handling audio, video or image media types
 *
 * Since: 0.10.31
 */
#define GST_ELEMENT_FACTORY_TYPE_AUDIOVIDEO_SINKS (GST_ELEMENT_FACTORY_TYPE_SINK | GST_ELEMENT_FACTORY_TYPE_MEDIA_AUDIO | GST_ELEMENT_FACTORY_TYPE_MEDIA_VIDEO | GST_ELEMENT_FACTORY_TYPE_MEDIA_IMAGE)

/**
 * GST_ELEMENT_FACTORY_TYPE_DECODABLE:
 *
 * All elements used to 'decode' streams (decoders, demuxers, parsers, depayloaders)
 *
 * Since: 0.10.31
 */
#define GST_ELEMENT_FACTORY_TYPE_DECODABLE \
  (GST_ELEMENT_FACTORY_TYPE_DECODER | GST_ELEMENT_FACTORY_TYPE_DEMUXER | GST_ELEMENT_FACTORY_TYPE_DEPAYLOADER | GST_ELEMENT_FACTORY_TYPE_PARSER)

/* Element klass defines */
#define GST_ELEMENT_FACTORY_KLASS_DECODER		"Decoder"
#define GST_ELEMENT_FACTORY_KLASS_ENCODER		"Encoder"
#define GST_ELEMENT_FACTORY_KLASS_SINK			"Sink"
#define GST_ELEMENT_FACTORY_KLASS_SRC			"Source"
#define GST_ELEMENT_FACTORY_KLASS_MUXER			"Muxer"
#define GST_ELEMENT_FACTORY_KLASS_DEMUXER		"Demuxer"
#define GST_ELEMENT_FACTORY_KLASS_PARSER		"Parser"
#define GST_ELEMENT_FACTORY_KLASS_PAYLOADER		"Payloader"
#define GST_ELEMENT_FACTORY_KLASS_DEPAYLOADER		"Depayloader"
#define GST_ELEMENT_FACTORY_KLASS_FORMATTER		"Formatter"

#define GST_ELEMENT_FACTORY_KLASS_MEDIA_VIDEO		"Video"
#define GST_ELEMENT_FACTORY_KLASS_MEDIA_AUDIO		"Audio"
#define GST_ELEMENT_FACTORY_KLASS_MEDIA_IMAGE		"Image"
#define GST_ELEMENT_FACTORY_KLASS_MEDIA_SUBTITLE	"Subtitle"
#define GST_ELEMENT_FACTORY_KLASS_MEDIA_METADATA	"Metadata"

gboolean      gst_element_factory_list_is_type      (GstElementFactory *factory,
						     GstElementFactoryListType type);

GList *       gst_element_factory_list_get_elements (GstElementFactoryListType type,
306
						     GstRank minrank) G_GNUC_MALLOC;
307 308


309 310
GList *       gst_element_factory_list_filter       (GList *list, const GstCaps *caps,
						     GstPadDirection direction,
311
						     gboolean subsetonly) G_GNUC_MALLOC;
312 313 314
G_END_DECLS

#endif /* __GST_ELEMENT_FACTORY_H__ */