gi-gst-1.0.22: GStreamer bindings
Copyright Will Thompson Iñaki García Etxebarria and Jonas Platte LGPL-2.1 Iñaki García Etxebarria None Haskell2010

GI.Gst.Structs.Caps

Description

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.

Synopsis

# Exported types

newtype Caps Source #

Memory-managed wrapper type.

Constructors

 Caps (ManagedPtr Caps)

#### Instances

Instances details
 Source # Instance detailsDefined in GI.Gst.Structs.Caps Methods(==) :: Caps -> Caps -> Bool #(/=) :: Caps -> Caps -> Bool # Source # Instance detailsDefined in GI.Gst.Structs.Caps Methods Source # Convert Caps to and from GValue with toGValue and fromGValue. Instance detailsDefined in GI.Gst.Structs.Caps Methods tag ~ 'AttrSet => Constructible Caps tag Source # Instance detailsDefined in GI.Gst.Structs.Caps Methodsnew :: MonadIO m => (ManagedPtr Caps -> Caps) -> [AttrOp Caps tag] -> m Caps #

newZeroCaps :: MonadIO m => m Caps Source #

Construct a Caps struct initialized to zero.

A convenience alias for Nothing :: Maybe Caps.

# Methods

## append

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

get caps #miniObject