GI.Gst.Structs.Caps

Caps (capabilities) are lightweight refcounted objects describing media types. They are composed of an array of Structure.

Caps are exposed on PadTemplate to describe all possible types a given pad can handle. They are also stored in the Registry along with a description of the Element.

Caps are exposed on the element pads using the padQueryCaps pad function. This function describes the possible types that the pad can handle or produce at runtime.

A Caps can be constructed with the following code fragment:

C code

 GstCaps *caps = gst_caps_new_simple ("video/x-raw",
    "format", G_TYPE_STRING, "I420",
    "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 Caps is fixed when it has no properties with ranges or lists. Use capsIsFixed to test for fixed caps. Fixed caps can be used in a caps event to notify downstream elements of the current media type.

Various methods exist to work with the media types such as subtracting or intersecting.

Be aware that the current Caps / Structure serialization into string has limited support for nested Caps / Structure fields. It can only support one level of nesting. Using more levels will lead to unexpected behavior when using serialization features, such as capsToString or valueSerialize and their counterparts.

Exported types

newtype Caps

Memory-managed wrapper type.

Constructors

Caps (ManagedPtr Caps)

Instances

BoxedObject Caps

Defined in GI.Gst.Structs.Caps

Methods

boxedType :: Caps -> IO GType

tag ~ AttrSet => Constructible Caps tag

Defined in GI.Gst.Structs.Caps

Methods

new :: MonadIO m => (ManagedPtr Caps -> Caps) -> [AttrOp Caps tag] -> m Caps

newZeroCaps :: MonadIO m => m Caps

Construct a Caps struct initialized to zero.

noCaps :: Maybe Caps

A convenience alias for Nothing :: Maybe Caps.

Methods

append

capsAppend

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps1: the Caps that will be appended to

-> Caps

caps2: the Caps to append

-> m ()

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.

appendStructure

capsAppendStructure

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: the Caps that will be appended to

-> Structure

structure: the Structure to append

-> m ()

Appends structure to caps. The structure is not copied; caps becomes the owner of structure.

appendStructureFull

capsAppendStructureFull

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: the Caps that will be appended to

-> Structure

structure: the Structure to append

-> Maybe CapsFeatures

features: the CapsFeatures to append

-> m ()

Appends structure with features to caps. The structure is not copied; caps becomes the owner of structure.

Since: 1.2

canIntersect

capsCanIntersect

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps1: a Caps to intersect

-> Caps

caps2: a Caps to intersect

-> m Bool

Returns: True if intersection would be not empty

Tries intersecting caps1 and caps2 and reports whether the result would not be empty

copy

capsCopy

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps.

-> m Caps

Returns: the new Caps

Creates a new Caps 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.

copyNth

capsCopyNth

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: the Caps to copy

-> Word32

nth: the nth structure to copy

-> m Caps

Returns: the new Caps

Creates a new Caps and appends a copy of the nth structure contained in caps.

filterAndMapInPlace

capsFilterAndMapInPlace

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps

-> CapsFilterMapFunc

func: a function to call for each field

-> m ()

Calls the provided function once for each structure and caps feature in the Caps. In contrast to capsForeach, the function may modify the structure and features. In contrast to capsFilterAndMapInPlace, the structure and features are removed from the caps if False is returned from the function. The caps must be mutable.

Since: 1.6

fixate

capsFixate

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps to fixate

-> m Caps

Returns: the fixated caps

Modifies the given caps into a representation with only fixed values. First the caps will be truncated and then the first structure will be fixated with structureFixate.

This function takes ownership of caps and will call gst_caps_make_writable() on it so you must not use caps afterwards unless you keep an additional reference to it with gst_caps_ref().

foreach

capsForeach

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps

-> CapsForeachFunc

func: a function to call for each field

-> m Bool

Returns: True if the supplied function returns True for each call, False otherwise.

Calls the provided function once for each structure and caps feature in the Caps. The function must not modify the fields. Also see capsMapInPlace and capsFilterAndMapInPlace.

Since: 1.6

fromString

capsFromString

Arguments

:: (HasCallStack, MonadIO m)

=> Text

string: a string to convert to Caps

-> m (Maybe Caps)

Returns: a newly allocated Caps

Converts caps from a string representation.

The current implementation of serialization will lead to unexpected results when there are nested Caps / Structure deeper than one level.

getFeatures

capsGetFeatures

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps

-> Word32

index: the index of the structure

-> m (Maybe CapsFeatures)

Returns: a pointer to the CapsFeatures corresponding to index

Finds the features in caps that has the index index, and returns it.

WARNING: This function takes a const GstCaps *, but returns a non-const GstCapsFeatures *. This is for programming convenience -- the caller should be aware that structures inside a constant Caps should not be modified. However, if you know the caps are writable, either because you have just copied them or made them writable with gst_caps_make_writable(), you may modify the features returned in the usual way, e.g. with functions like capsFeaturesAdd.

You do not need to free or unref the structure returned, it belongs to the Caps.

Since: 1.2

getSize

capsGetSize

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps

-> m Word32

Returns: the number of structures that caps contains

Gets the number of structures contained in caps.

getStructure

capsGetStructure

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps

-> Word32

index: the index of the structure

-> m Structure

Returns: a pointer to the Structure corresponding to index

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 Caps should not be modified. However, if you know the caps are writable, either because you have just copied them or made them writable with gst_caps_make_writable(), you may modify the structure returned in the usual way, e.g. with functions like gst_structure_set().

You do not need to free or unref the structure returned, it belongs to the Caps.

intersect

capsIntersect

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps1: a Caps to intersect

-> Caps

caps2: a Caps to intersect

-> m Caps

Returns: the new Caps

Creates a new Caps that contains all the formats that are common to both caps1 and caps2. Defaults to CapsIntersectModeZigZag mode.

intersectFull

capsIntersectFull

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps1: a Caps to intersect

-> Caps

caps2: a Caps to intersect

-> CapsIntersectMode

mode: The intersection algorithm/mode to use

-> m Caps

Returns: the new Caps

Creates a new Caps that contains all the formats that are common to both caps1 and caps2, the order is defined by the CapsIntersectMode used.

isAlwaysCompatible

capsIsAlwaysCompatible

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps1: the Caps to test

-> Caps

caps2: the Caps to test

-> m Bool

Returns: True if caps1 is a subset of caps2.

A given Caps 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.

isAny

capsIsAny

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: the Caps to test

-> m Bool

Returns: True if caps represents any format.

Determines if caps represents any media format.

isEmpty

capsIsEmpty

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: the Caps to test

-> m Bool

Returns: True if caps represents no formats.

Determines if caps represents no media formats.

isEqual

capsIsEqual

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps1: a Caps

-> Caps

caps2: another Caps

-> m Bool

Returns: True if both caps are equal.

Checks if the given caps represent the same set of caps.

isEqualFixed

capsIsEqualFixed

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps1: the Caps to test

-> Caps

caps2: the Caps to test

-> m Bool

Returns: True if the arguments represent the same format

Tests if two Caps are equal. This function only works on fixed Caps.

isFixed

capsIsFixed

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: the Caps to test

-> m Bool

Returns: True if caps is fixed

Fixed Caps 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.

isStrictlyEqual

capsIsStrictlyEqual

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps1: a Caps

-> Caps

caps2: another Caps

-> m Bool

Returns: True if both caps are strictly equal.

Checks if the given caps are exactly the same set of caps.

isSubset

capsIsSubset

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

subset: a Caps

-> Caps

superset: a potentially greater Caps

-> m Bool

Returns: True if subset is a subset of superset

Checks if all caps represented by subset are also represented by superset.

isSubsetStructure

capsIsSubsetStructure

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps

-> Structure

structure: a potential Structure subset of caps

-> m Bool

Returns: True if structure is a subset of caps

Checks if structure is a subset of caps. See capsIsSubset for more information.

isSubsetStructureFull

capsIsSubsetStructureFull

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps

-> Structure

structure: a potential Structure subset of caps

-> Maybe CapsFeatures

features: a CapsFeatures for structure

-> m Bool

Returns: True if structure is a subset of caps

Checks if structure is a subset of caps. See capsIsSubset for more information.

Since: 1.2

mapInPlace

capsMapInPlace

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps

-> CapsMapFunc

func: a function to call for each field

-> m Bool

Returns: True if the supplied function returns True for each call, False otherwise.

Calls the provided function once for each structure and caps feature in the Caps. In contrast to capsForeach, the function may modify but not delete the structures and features. The caps must be mutable.

Since: 1.6

merge

capsMerge

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps1: the Caps that will take the new entries

-> Caps

caps2: the Caps to merge in

-> m Caps

Returns: the merged caps.

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 a writable copy of caps1, and then caps2 is freed. If either caps is ANY, the resulting caps will be ANY.

mergeStructure

capsMergeStructure

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: the Caps to merge into

-> Structure

structure: the Structure to merge

-> m Caps

Returns: the merged caps.

Appends structure to caps if its not already expressed by caps.

mergeStructureFull

capsMergeStructureFull

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: the Caps to merge into

-> Structure

structure: the Structure to merge

-> Maybe CapsFeatures

features: the CapsFeatures to merge

-> m Caps

Returns: the merged caps.

Appends structure with features to caps if its not already expressed by caps.

Since: 1.2

newAny

capsNewAny

Arguments

:: (HasCallStack, MonadIO m)

=> m Caps

Returns: the new Caps

Creates a new Caps that indicates that it is compatible with any media format.

newEmpty

capsNewEmpty

Arguments

:: (HasCallStack, MonadIO m)

=> m Caps

Returns: the new Caps

Creates a new Caps that is empty. That is, the returned Caps contains no media formats. The Caps is guaranteed to be writable. Caller is responsible for unreffing the returned caps.

newEmptySimple

capsNewEmptySimple

Arguments

:: (HasCallStack, MonadIO m)

=> Text

mediaType: the media type of the structure

-> m Caps

Returns: the new Caps

Creates a new Caps that contains one Structure with name mediaType. Caller is responsible for unreffing the returned caps.

normalize

capsNormalize

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps to normalize

-> m Caps

Returns: the normalized Caps

Returns a Caps that represents the same set of formats as caps, but contains no lists. Each list is expanded into separate gstStructures.

This function takes ownership of caps and will call gst_caps_make_writable() on it so you must not use caps afterwards unless you keep an additional reference to it with gst_caps_ref().

removeStructure

capsRemoveStructure

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: the Caps to remove from

-> Word32

idx: Index of the structure to remove

-> m ()

removes the structure with the given index from the list of structures contained in caps.

setFeatures

capsSetFeatures

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps

-> Word32

index: the index of the structure

-> Maybe CapsFeatures

features: the CapsFeatures to set

-> m ()

Sets the CapsFeatures features for the structure at index.

Since: 1.2

setFeaturesSimple

capsSetFeaturesSimple

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps

-> Maybe CapsFeatures

features: the CapsFeatures to set

-> m ()

Sets the CapsFeatures features for all the structures of caps.

Since: 1.16

setValue

capsSetValue

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a writable caps

-> Text

field: name of the field to set

-> GValue

value: value to set the field to

-> m ()

Sets the given field on all structures of caps to the given value. This is a convenience function for calling structureSetValue on all structures of caps.

simplify

capsSimplify

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps to simplify

-> m Caps

Returns: The simplified caps.

Converts the given caps 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.

This function takes ownership of caps and will call gst_caps_make_writable() on it if necessary, so you must not use caps afterwards unless you keep an additional reference to it with gst_caps_ref().

This method does not preserve the original order of caps.

stealStructure

capsStealStructure

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: the Caps to retrieve from

-> Word32

index: Index of the structure to retrieve

-> m (Maybe Structure)

Returns: a pointer to the Structure corresponding to index.

Retrieves the structure with the given index from the list of structures contained in caps. The caller becomes the owner of the returned structure.

subtract

capsSubtract

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

minuend: Caps to subtract from

-> Caps

subtrahend: Caps to subtract

-> m Caps

Returns: the resulting caps

Subtracts the subtrahend from the minuend. > This function does not work reliably if optional properties for caps > are included on one caps and omitted on the other.

toString

capsToString

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: a Caps

-> m Text

Returns: a newly allocated string representing caps.

Converts caps to a string representation. This string representation can be converted back to a Caps by capsFromString.

For debugging purposes its easier to do something like this:

C code

GST_LOG ("caps are %" GST_PTR_FORMAT, caps);

This prints the caps in human readable form.

The current implementation of serialization will lead to unexpected results when there are nested Caps / Structure deeper than one level.

truncate

capsTruncate

Arguments

:: (HasCallStack, MonadIO m)

=> Caps

caps: the Caps to truncate

-> m Caps

Returns: truncated caps

Discard all but the first structure from caps. Useful when fixating.

This function takes ownership of caps and will call gst_caps_make_writable() on it if necessary, so you must not use caps afterwards unless you keep an additional reference to it with gst_caps_ref().

Properties

miniObject

the parent type

getCapsMiniObject :: MonadIO m => Caps -> m MiniObject

Get the value of the “mini_object” field. When overloading is enabled, this is equivalent to

get caps #miniObject