gstreamer/docs/design/gstprofile.h

232 lines
7.3 KiB
C
Raw Normal View History

/* GStreamer encoding profiles library
* Copyright (C) 2009 Edward Hervey <edward.hervey@collabora.co.uk>
* (C) 2009 Nokia Corporation
*
* 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_PROFILE_H__
#define __GST_PROFILE_H__
#include <gst/gst.h>
typedef enum {
GST_ENCODING_PROFILE_UNKNOWN,
GST_ENCODING_PROFILE_VIDEO,
GST_ENCODING_PROFILE_AUDIO,
GST_ENCODING_PROFILE_TEXT
/* Room for extenstion */
} GstEncodingProfileType;
typedef struct _GstEncodingTarget GstEncodingTarget;
typedef struct _GstEncodingProfile GstEncodingProfile;
typedef struct _GstStreamEncodingProfile GstStreamEncodingProfile;
typedef struct _GstVideoEncodingProfile GstVideoEncodingProfile;
/* FIXME/UNKNOWNS
*
* Should encoding categories be well-known strings/quarks ?
*
*/
/**
* GstEncodingTarget:
* @name: The name of the target profile.
* @category: The target category (device, service, use-case).
* @profiles: A list of #GstProfile this device supports.
*
*/
struct _GstEncodingTarget {
gchar *name;
gchar *category;
GList *profiles;
}
/**
* GstEncodingProfile:
* @name: The name of the profile
* @format: The GStreamer mime type corresponding to the muxing format.
* @preset: The name of the #GstPreset(s) to be used on the muxer. This is optional.
* @multipass: Whether this profile is a multi-pass profile or not.
* @encodingprofiles: A list of #GstStreamEncodingProfile for the various streams.
*
*/
struct _GstEncodingProfile {
gchar *name;
gchar *format;
gchar *preset;
gboolean multipass;
GList *encodingprofiles;
};
/**
* GstStreamEncodingProfile:
* @type: Type of profile
* @format: The GStreamer mime type corresponding to the encoding format.
* @preset: The name of the #GstPreset to be used on the encoder. This is optional.
* @restriction: The #GstCaps restricting the input. This is optional.
* @presence: The number of streams that can be created. 0 => any.
*/
struct _GstStreamEncodingProfile {
GstEncodingProfileType type;
gchar *format;
gchar *preset;
GstCaps *restriction;
guint presence;
};
/**
* GstVideoEncodingProfile:
* @profile: common #GstEncodingProfile part.
* @pass: The pass number if this is part of a multi-pass profile. Starts at 1
* for multi-pass. Set to 0 if this is not part of a multi-pass profile.
2009-11-12 18:14:35 +00:00
* @variable_framerate: Do not enforce framerate on incoming raw stream. Default
* is FALSE.
*/
struct _GstVideoEncodingProfile {
GstStreamEncodingProfile profile;
guint pass;
2009-11-12 18:14:35 +00:00
gboolean variable_framerate;
};
/* Generic helper API */
/**
* gst_encoding_category_list_target:
* @category: a profile target category name. Can be NULL.
*
* Returns the list of all available #GstProfileTarget for the given @category.
* If @category is #NULL, then all available #GstProfileTarget are returned.
*/
GList *gst_encoding_category_list_target (gchar *category);
/**
* list available profile target categories
*/
GList *gst_profile_list_target_categories ();
gboolean gst_profile_target_save (GstProfileTarget *target);
2009-11-12 18:14:35 +00:00
/**
* gst_encoding_profile_get_input_caps:
* @profile: a #GstEncodingProfile
*
* Returns: the list of all caps the profile can accept. Caller must call
* gst_cap_unref on all unwanted caps once it is done with the list.
*/
GList * gst_profile_get_input_caps (GstEncodingProfile *profile);
/*
* Application convenience methods (possibly to be added in gst-pb-utils)
*/
/**
* gst_pb_utils_create_encoder:
* @caps: The #GstCaps corresponding to a codec format
* @preset: The name of a preset
* @name: The name to give to the returned instance, can be #NULL.
*
* Creates an encoder which can output the given @caps. If several encoders can
* output the given @caps, then the one with the highest rank will be picked.
* If a @preset is specified, it will be applied to the created encoder before
* returning it.
* If a @preset is specified, then the highest-ranked encoder that can accept
* the givein preset will be returned.
*
* Returns: The encoder instance with the preset applied if it is available.
* #NULL if no encoder is available.
*/
GstElement *gst_pb_utils_create_encoder(GstCaps *caps, gchar *preset, gchar *name);
/**
* gst_pb_utils_create_encoder_format:
*
* Convenience version of @gst_pb_utils_create_encoder except one does not need
* to create a #GstCaps.
*/
GstElement *gst_pb_utils_create_encoder_format(gchar *format, gchar *preset,
gchar *name);
/**
* gst_pb_utils_create_muxer:
* @caps: The #GstCaps corresponding to a codec format
* @preset: The name of a preset
*
* Creates an muxer which can output the given @caps. If several muxers can
* output the given @caps, then the one with the highest rank will be picked.
* If a @preset is specified, it will be applied to the created muxer before
* returning it.
* If a @preset is specified, then the highest-ranked muxer that can accept
* the givein preset will be returned.
*
* Returns: The muxer instance with the preset applied if it is available.
* #NULL if no muxer is available.
*/
GstElement *gst_pb_utils_create_muxer(GstCaps *caps, gchar *preset);
/**
* gst_pb_utils_create_muxer_format:
*
* Convenience version of @gst_pb_utils_create_muxer except one does not need
* to create a #GstCaps.
*/
GstElement *gst_pb_utils_create_muxer_format(gchar *format, gchar *preset,
gchar *name);
/**
* gst_pb_utils_encoders_compatible_with_muxer:
* @muxer: a muxer instance
*
* Finds a list of available encoders whose output can be fed to the given
* @muxer.
*
* Returns: A list of compatible encoders, or #NULL if none can be found.
*/
GList *gst_pb_utils_encoders_compatible_with_muxer(GstElement *muxer);
GList *gst_pb_utils_muxers_compatible_with_encoder(GstElement *encoder);
/*
* GstPreset modifications
*/
/**
* gst_preset_create:
* @preset: The #GstPreset on which to create the preset
* @name: A name for the preset
* @properties: The properties
*
* Creates a new preset with the given properties. This preset will only
* exist during the lifetime of the process.
* If you wish to use it after the lifetime of the process, you must call
* @gst_preset_save_preset.
*
* Returns: #TRUE if the preset could be created, else #FALSE.
*/
gboolean gst_preset_create (GstPreset *preset, gchar *name,
GstStructure *properties);
/**
* gst_preset_reset:
* @preset: a #GstPreset
*
* Sets all the properties of the element back to their default values.
*/
/* FIXME : This could actually be put at the GstObject level, or maybe even
* at the GObject level. */
void gst_preset_reset (GstPreset *preset);
#endif /* __GST_PROFILE_H__ */