alternative to assert

[gtkD.git] / gtkD / srcgstreamer / gstreamer / Caps.d

/*
 * This file is part of gtkD.
 *
 * gtkD is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * gtkD 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 Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with gtkD; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
 
// generated automatically - do not change
// find conversion definition on APILookup.txt
// implement new conversion functionalities on the wrap.utils pakage

/*
 * Conversion parameters:
 * inFile  = gstreamer-GstCaps.html
 * outPack = gstreamer
 * outFile = Caps
 * strct   = GstCaps
 * realStrct=
 * ctorStrct=
 * clss    = Caps
 * interf  = 
 * class Code: Yes
 * interface Code: No
 * template for:
 * extend  = 
 * implements:
 * prefixes:
 *      - gst_caps_
 *      - gst_
 * omit structs:
 * omit prefixes:
 * omit code:
 *      - gst_caps_save_thyself
 *      - gst_caps_load_thyself
 *      - gst_caps_new_any
 * imports:
 *      - glib.Str
 *      - gstreamer.Structure
 * structWrap:
 *      - GstCaps* -> Caps
 *      - GstStructure* -> Structure
 * module aliases:
 * local aliases:
 */

module gstreamer.Caps;

private import gstreamerc.gstreamertypes;

private import gstreamerc.gstreamer;

private import glib.Str;
private import gstreamer.Structure;



/**
 * Description
 * Caps (capabilities) are lighweight refcounted objects describing media types.
 * They are composed of an array of GstStructure.
 * Caps are exposed on GstPadTemplate to describe all possible types a
 * given pad can handle. They are also stored in the GstRegistry along with
 * a description of the GstElement.
 * Caps are exposed on the element pads using the gst_pad_get_caps() pad
 * function. This function describes the possible types that the pad can
 * handle or produce at runtime.
 * Caps are also attached to buffers to describe to content of the data
 * pointed to by the buffer with gst_buffer_set_caps(). Caps attached to
 * a GstBuffer allow for format negotiation upstream and downstream.
 * A GstCaps can be constructed with the following code fragment:
 * Example4.Creating caps
 *  GstCaps *caps;
 *  caps = gst_caps_new_simple ("video/x-raw-yuv",
 *  "format", GST_TYPE_FOURCC, GST_MAKE_FOURCC ('I', '4', '2', '0'),
 *  "framerate", GST_TYPE_FRACTION, 25, 1,
 *  "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
 *  "width", G_TYPE_INT, 320,
 *  "height", G_TYPE_INT, 240,
 *  NULL);
 * A GstCaps is fixed when it has no properties with ranges or lists. Use
 * gst_caps_is_fixed() to test for fixed caps. Only fixed caps can be
 * set on a GstPad or GstBuffer.
 * Various methods exist to work with the media types such as subtracting
 * or intersecting.
 * Last reviewed on 2007-02-13 (0.10.10)
 */
public class Caps
{
        
        /** the main Gtk struct */
        protected GstCaps* gstCaps;
        
        
        public GstCaps* getCapsStruct()
        {
                return gstCaps;
        }
        
        
        /** the main Gtk struct as a void* */
        protected void* getStruct()
        {
                return cast(void*)gstCaps;
        }
        
        /**
         * Sets our main struct and passes it to the parent class
         */
        public this (GstCaps* gstCaps)
        {
                this.gstCaps = gstCaps;
        }
        
        /**
         * Creates a new GstCaps that indicates that it is compatible with
         * any media format.
         * Returns:
         *  the new GstCaps
         */
        public static Caps newAny()
        {
                // GstCaps* gst_caps_new_any (void);
                return new Caps(cast(GstCaps*)gst_caps_new_any() );
        }
        
        /**
         */
        
        
        
        
        
        
        
        
        
        
        
        
        
        /**
         * Creates a new GstCaps that is empty. That is, the returned
         * GstCaps contains no media formats.
         * Caller is responsible for unreffing the returned caps.
         * Returns:
         *  the new GstCaps
         */
        public this ()
        {
                // GstCaps* gst_caps_new_empty (void);
                this(cast(GstCaps*)gst_caps_new_empty() );
        }
        
        
        /**
         * Creates a new GstCaps that contains one GstStructure. The
         * structure is defined by the arguments, which have the same format
         * as gst_structure_new().
         * Caller is responsible for unreffing the returned caps.
         * media_type:
         *  the media type of the structure
         * fieldname:
         *  first field to set
         * ...:
         *  additional arguments
         * Returns:
         *  the new GstCaps
         */
        public this (char[] mediaType, char[] fieldname, ... )
        {
                // GstCaps* gst_caps_new_simple (const char *media_type,  const char *fieldname,  ...);
                this(cast(GstCaps*)gst_caps_new_simple(Str.toStringz(mediaType), Str.toStringz(fieldname)) );
        }
        
        /**
         * Creates a new GstCaps and adds all the structures listed as
         * arguments. The list must be NULL-terminated. The structures
         * are not copied; the returned GstCaps owns the structures.
         * struct1:
         *  the first structure to add
         * ...:
         *  additional structures to add
         * Returns:
         *  the new GstCaps
         */
        public this (Structure struct1, ... )
        {
                // GstCaps* gst_caps_new_full (GstStructure *struct1,  ...);
                this(cast(GstCaps*)gst_caps_new_full((struct1 is null) ? null : struct1.getStructureStruct()) );
        }
        
        /**
         * Creates a new GstCaps and adds all the structures listed as
         * arguments. The list must be NULL-terminated. The structures
         * are not copied; the returned GstCaps owns the structures.
         * structure:
         *  the first structure to add
         * var_args:
         *  additional structures to add
         * Returns:
         *  the new GstCaps
         */
        public this (Structure structure, void* varArgs)
        {
                // GstCaps* gst_caps_new_full_valist (GstStructure *structure,  va_list var_args);
                this(cast(GstCaps*)gst_caps_new_full_valist((structure is null) ? null : structure.getStructureStruct(), varArgs) );
        }
        
        /**
         * Creates a new GstCaps as a copy of the old caps. The new caps will have a
         * refcount of 1, owned by the caller. The structures are copied as well.
         * Note that this function is the semantic equivalent of a gst_caps_ref()
         * followed by a gst_caps_make_writable(). If you only want to hold on to a
         * reference to the data, you should use gst_caps_ref().
         * When you are finished with the caps, call gst_caps_unref() on it.
         * caps:
         *  the GstCaps to copy
         * Returns:
         *  the new GstCaps
         */
        public Caps copy()
        {
                // GstCaps* gst_caps_copy (const GstCaps *caps);
                return new Caps( gst_caps_copy(gstCaps) );
        }
        
        /**
         * Creates a new GstCaps and appends a copy of the nth structure
         * contained in caps.
         * caps:
         *  the GstCaps to copy
         * nth:
         *  the nth structure to copy
         * Returns:
         *  the new GstCaps
         */
        public Caps copyNth(uint nth)
        {
                // GstCaps* gst_caps_copy_nth (const GstCaps *caps,  guint nth);
                return new Caps( gst_caps_copy_nth(gstCaps, nth) );
        }
        
        /**
         * Converts a GstStaticCaps to a GstCaps.
         * static_caps:
         *  the GstStaticCaps to convert
         * Returns:
         *  A pointer to the GstCaps. Unref after usage. Since the
         * core holds an additional ref to the returned caps,
         * use gst_caps_make_writable() on the returned caps to modify it.
         */
        public static Caps staticCapsGet(GstStaticCaps* staticCaps)
        {
                // GstCaps* gst_static_caps_get (GstStaticCaps *static_caps);
                return new Caps( gst_static_caps_get(staticCaps) );
        }
        
        /**
         * Appends the structures contained in caps2 to caps1. The structures in
         * caps2 are not copied -- they are transferred to caps1, and then caps2 is
         * freed. If either caps is ANY, the resulting caps will be ANY.
         * caps1:
         *  the GstCaps that will be appended to
         * caps2:
         *  the GstCaps to append
         */
        public void append(Caps caps2)
        {
                // void gst_caps_append (GstCaps *caps1,  GstCaps *caps2);
                gst_caps_append(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct());
        }
        
        /**
         * Appends the structures contained in caps2 to caps1 if they are not yet
         * expressed by caps1. The structures in caps2 are not copied -- they are
         * transferred to caps1, and then caps2 is freed.
         * If either caps is ANY, the resulting caps will be ANY.
         * caps1:
         *  the GstCaps that will take the new entries
         * caps2:
         *  the GstCaps to merge in
         * Since 0.10.10
         */
        public void merge(Caps caps2)
        {
                // void gst_caps_merge (GstCaps *caps1,  GstCaps *caps2);
                gst_caps_merge(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct());
        }
        
        /**
         * Appends structure to caps. The structure is not copied; caps
         * becomes the owner of structure.
         * caps:
         *  the GstCaps that will be appended to
         * structure:
         *  the GstStructure to append
         */
        public void appendStructure(Structure structure)
        {
                // void gst_caps_append_structure (GstCaps *caps,  GstStructure *structure);
                gst_caps_append_structure(gstCaps, (structure is null) ? null : structure.getStructureStruct());
        }
        
        /**
         * removes the stucture with the given index from the list of structures
         * contained in caps.
         * caps:
         *  the GstCaps to remove from
         * idx:
         *  Index of the structure to remove
         */
        public void removeStructure(uint idx)
        {
                // void gst_caps_remove_structure (GstCaps *caps,  guint idx);
                gst_caps_remove_structure(gstCaps, idx);
        }
        
        /**
         * Appends structure to caps if its not already expressed by caps. The
         * structure is not copied; caps becomes the owner of structure.
         * caps:
         *  the GstCaps that will the the new structure
         * structure:
         *  the GstStructure to merge
         */
        public void mergeStructure(Structure structure)
        {
                // void gst_caps_merge_structure (GstCaps *caps,  GstStructure *structure);
                gst_caps_merge_structure(gstCaps, (structure is null) ? null : structure.getStructureStruct());
        }
        
        /**
         * Gets the number of structures contained in caps.
         * caps:
         *  a GstCaps
         * Returns:
         *  the number of structures that caps contains
         */
        public uint getSize()
        {
                // guint gst_caps_get_size (const GstCaps *caps);
                return gst_caps_get_size(gstCaps);
        }
        
        /**
         * Finds the structure in caps that has the index index, and
         * returns it.
         * WARNING: This function takes a const GstCaps *, but returns a
         * non-const GstStructure *. This is for programming convenience --
         * the caller should be aware that structures inside a constant
         * GstCaps should not be modified.
         * caps:
         *  a GstCaps
         * index:
         *  the index of the structure
         * Returns:
         *  a pointer to the GstStructure corresponding to index
         */
        public Structure getStructure(uint index)
        {
                // GstStructure* gst_caps_get_structure (const GstCaps *caps,  guint index);
                return new Structure( gst_caps_get_structure(gstCaps, index) );
        }
        
        /**
         * Sets fields in a simple GstCaps. A simple GstCaps is one that
         * only has one structure. The arguments must be passed in the same
         * manner as gst_structure_set(), and be NULL-terminated.
         * caps:
         *  the GstCaps to set
         * field:
         *  first field to set
         * ...:
         *  additional parameters
         */
        public void setSimple(char[] field, ... )
        {
                // void gst_caps_set_simple (GstCaps *caps,  char *field,  ...);
                gst_caps_set_simple(gstCaps, Str.toStringz(field));
        }
        
        /**
         * Sets fields in a simple GstCaps. A simple GstCaps is one that
         * only has one structure. The arguments must be passed in the same
         * manner as gst_structure_set(), and be NULL-terminated.
         * caps:
         *  the GstCaps to copy
         * field:
         *  first field to set
         * varargs:
         *  additional parameters
         */
        public void setSimpleValist(char[] field, void* varargs)
        {
                // void gst_caps_set_simple_valist (GstCaps *caps,  char *field,  va_list varargs);
                gst_caps_set_simple_valist(gstCaps, Str.toStringz(field), varargs);
        }
        
        /**
         * Determines if caps represents any media format.
         * caps:
         *  the GstCaps to test
         * Returns:
         *  TRUE if caps represents any format.
         */
        public int isAny()
        {
                // gboolean gst_caps_is_any (const GstCaps *caps);
                return gst_caps_is_any(gstCaps);
        }
        
        /**
         * Determines if caps represents no media formats.
         * caps:
         *  the GstCaps to test
         * Returns:
         *  TRUE if caps represents no formats.
         */
        public int isEmpty()
        {
                // gboolean gst_caps_is_empty (const GstCaps *caps);
                return gst_caps_is_empty(gstCaps);
        }
        
        /**
         * Fixed GstCaps describe exactly one format, that is, they have exactly
         * one structure, and each field in the structure describes a fixed type.
         * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
         * caps:
         *  the GstCaps to test
         * Returns:
         *  TRUE if caps is fixed
         */
        public int isFixed()
        {
                // gboolean gst_caps_is_fixed (const GstCaps *caps);
                return gst_caps_is_fixed(gstCaps);
        }
        
        /**
         * Checks if the given caps represent the same set of caps.
         * Note
         * This function does not work reliably if optional properties for caps
         * are included on one caps and omitted on the other.
         * This function deals correctly with passing NULL for any of the caps.
         * caps1:
         *  a GstCaps
         * caps2:
         *  another GstCaps
         * Returns:
         *  TRUE if both caps are equal.
         */
        public int isEqual(Caps caps2)
        {
                // gboolean gst_caps_is_equal (const GstCaps *caps1,  const GstCaps *caps2);
                return gst_caps_is_equal(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct());
        }
        
        /**
         * Tests if two GstCaps are equal. This function only works on fixed
         * GstCaps.
         * caps1:
         *  the GstCaps to test
         * caps2:
         *  the GstCaps to test
         * Returns:
         *  TRUE if the arguments represent the same format
         */
        public int isEqualFixed(Caps caps2)
        {
                // gboolean gst_caps_is_equal_fixed (const GstCaps *caps1,  const GstCaps *caps2);
                return gst_caps_is_equal_fixed(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct());
        }
        
        /**
         * A given GstCaps structure is always compatible with another if
         * every media format that is in the first is also contained in the
         * second. That is, caps1 is a subset of caps2.
         * caps1:
         *  the GstCaps to test
         * caps2:
         *  the GstCaps to test
         * Returns:
         *  TRUE if caps1 is a subset of caps2.
         */
        public int isAlwaysCompatible(Caps caps2)
        {
                // gboolean gst_caps_is_always_compatible (const GstCaps *caps1,  const GstCaps *caps2);
                return gst_caps_is_always_compatible(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct());
        }
        
        /**
         * Checks if all caps represented by subset are also represented by superset.
         * Note
         * This function does not work reliably if optional properties for caps
         * are included on one caps and omitted on the other.
         * subset:
         *  a GstCaps
         * superset:
         *  a potentially greater GstCaps
         * Returns:
         *  TRUE if subset is a subset of superset
         */
        public int isSubset(Caps superset)
        {
                // gboolean gst_caps_is_subset (const GstCaps *subset,  const GstCaps *superset);
                return gst_caps_is_subset(gstCaps, (superset is null) ? null : superset.getCapsStruct());
        }
        
        /**
         * Creates a new GstCaps that contains all the formats that are common
         * to both caps1 and caps2.
         * caps1:
         *  a GstCaps to intersect
         * caps2:
         *  a GstCaps to intersect
         * Returns:
         *  the new GstCaps
         */
        public Caps intersect(Caps caps2)
        {
                // GstCaps* gst_caps_intersect (const GstCaps *caps1,  const GstCaps *caps2);
                return new Caps( gst_caps_intersect(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct()) );
        }
        
        /**
         * Creates a new GstCaps that contains all the formats that are in
         * either caps1 and caps2.
         * caps1:
         *  a GstCaps to union
         * caps2:
         *  a GstCaps to union
         * Returns:
         *  the new GstCaps
         */
        public Caps unio(Caps caps2)
        {
                // GstCaps* gst_caps_union (const GstCaps *caps1,  const GstCaps *caps2);
                return new Caps( gst_caps_union(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct()) );
        }
        
        /**
         * Creates a new GstCaps that represents the same set of formats as
         * caps, but contains no lists. Each list is expanded into separate
         * GstStructures.
         * caps:
         *  a GstCaps to normalize
         * Returns:
         *  the new GstCaps
         */
        public Caps normalize()
        {
                // GstCaps* gst_caps_normalize (const GstCaps *caps);
                return new Caps( gst_caps_normalize(gstCaps) );
        }
        
        /**
         * Modifies the given caps inplace into a representation that represents the
         * same set of formats, but in a simpler form. Component structures that are
         * identical are merged. Component structures that have values that can be
         * merged are also merged.
         * caps:
         *  a GstCaps to simplify
         * Returns:
         *  TRUE, if the caps could be simplified
         */
        public int doSimplify()
        {
                // gboolean gst_caps_do_simplify (GstCaps *caps);
                return gst_caps_do_simplify(gstCaps);
        }
        
        
        
        /**
         * Replaces *caps with newcaps. Unrefs the GstCaps in the location
         * pointed to by caps, if applicable, then modifies caps to point to
         * newcaps. An additional ref on newcaps is taken.
         * This function does not take any locks so you might want to lock
         * the object owning caps pointer.
         * caps:
         *  a pointer to GstCaps
         * newcaps:
         *  a GstCaps to replace *caps
         */
        public static void replace(GstCaps** caps, Caps newcaps)
        {
                // void gst_caps_replace (GstCaps **caps,  GstCaps *newcaps);
                gst_caps_replace(caps, (newcaps is null) ? null : newcaps.getCapsStruct());
        }
        
        /**
         * Converts caps to a string representation. This string representation
         * can be converted back to a GstCaps by gst_caps_from_string().
         * For debugging purposes its easier to do something like this:
         *  GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
         * This prints the caps in human readble form.
         * caps:
         *  a GstCaps
         * Returns:
         *  a newly allocated string representing caps.
         */
        public char[] toString()
        {
                // gchar* gst_caps_to_string (const GstCaps *caps);
                return Str.toString(gst_caps_to_string(gstCaps) );
        }
        
        /**
         * Converts caps from a string representation.
         * string:
         *  a string to convert to GstCaps
         * Returns:
         *  a newly allocated GstCaps
         */
        public static Caps fromString(char[] string)
        {
                // GstCaps* gst_caps_from_string (const gchar *string);
                return new Caps( gst_caps_from_string(Str.toStringz(string)) );
        }
        
        /**
         * Subtracts the subtrahend from the minuend.
         * Note
         * This function does not work reliably if optional properties for caps
         * are included on one caps and omitted on the other.
         * minuend:
         *  GstCaps to substract from
         * subtrahend:
         *  GstCaps to substract
         * Returns:
         *  the resulting caps
         */
        public Caps subtract(Caps subtrahend)
        {
                // GstCaps* gst_caps_subtract (const GstCaps *minuend,  const GstCaps *subtrahend);
                return new Caps( gst_caps_subtract(gstCaps, (subtrahend is null) ? null : subtrahend.getCapsStruct()) );
        }
        
        /**
         * Returns a writable copy of caps.
         * If there is only one reference count on caps, the caller must be the owner,
         * and so this function will return the caps object unchanged. If on the other
         * hand there is more than one reference on the object, a new caps object will
         * be returned. The caller's reference on caps will be removed, and instead the
         * caller will own a reference to the returned object.
         * In short, this function unrefs the caps in the argument and refs the caps
         * that it returns. Don't access the argument after calling this function. See
         * also: gst_caps_ref().
         * caps:
         *  the GstCaps to make writable
         * Returns:
         *  the same GstCaps object.
         */
        public Caps makeWritable()
        {
                // GstCaps* gst_caps_make_writable (GstCaps *caps);
                return new Caps( gst_caps_make_writable(gstCaps) );
        }
        
        /**
         * Add a reference to a GstCaps object.
         * From this point on, until the caller calls gst_caps_unref() or
         * gst_caps_make_writable(), it is guaranteed that the caps object will not
         * change. This means its structures won't change, etc. To use a GstCaps
         * object, you must always have a refcount on it -- either the one made
         * implicitly by gst_caps_new(), or via taking one explicitly with this
         * function.
         * caps:
         *  the GstCaps to reference
         * Returns:
         *  the same GstCaps object.
         */
        public Caps doref()
        {
                // GstCaps* gst_caps_ref (GstCaps *caps);
                return new Caps( gst_caps_ref(gstCaps) );
        }
        
        /**
         * Destructively discard all but the first structure from caps. Useful when
         * fixating. caps must be writable.
         * caps:
         *  the GstCaps to truncate
         */
        public void truncate()
        {
                // void gst_caps_truncate (GstCaps *caps);
                gst_caps_truncate(gstCaps);
        }
        
        /**
         * Unref a GstCaps and and free all its structures and the
         * structures' values when the refcount reaches 0.
         * caps:
         *  the GstCaps to unref
         * See Also
         * GstStructure
         */
        public void unref()
        {
                // void gst_caps_unref (GstCaps *caps);
                gst_caps_unref(gstCaps);
        }
}