Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
- Exported types
- Methods
- append
- appendStructure
- appendStructureFull
- canIntersect
- copy
- copyNth
- filterAndMapInPlace
- fixate
- foreach
- fromString
- getFeatures
- getSize
- getStructure
- intersect
- intersectFull
- isAlwaysCompatible
- isAny
- isEmpty
- isEqual
- isEqualFixed
- isFixed
- isStrictlyEqual
- isSubset
- isSubsetStructure
- isSubsetStructureFull
- mapInPlace
- merge
- mergeStructure
- mergeStructureFull
- newAny
- newEmpty
- newEmptySimple
- normalize
- removeStructure
- serialize
- setFeatures
- setFeaturesSimple
- setValue
- simplify
- stealStructure
- subtract
- toString
- truncate
- Properties
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
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 fields 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 until 1.20 the Caps
/ Structure
serialization into string
had limited support for nested Caps
/ Structure
fields. It could only
support one level of nesting. Using more levels would lead to unexpected
behavior when using serialization features, such as capsToString
or
valueSerialize
and their counterparts.
Synopsis
- newtype Caps = Caps (ManagedPtr Caps)
- newZeroCaps :: MonadIO m => m Caps
- capsAppend :: (HasCallStack, MonadIO m) => Caps -> Caps -> m ()
- capsAppendStructure :: (HasCallStack, MonadIO m) => Caps -> Structure -> m ()
- capsAppendStructureFull :: (HasCallStack, MonadIO m) => Caps -> Structure -> Maybe CapsFeatures -> m ()
- capsCanIntersect :: (HasCallStack, MonadIO m) => Caps -> Caps -> m Bool
- capsCopy :: (HasCallStack, MonadIO m) => Caps -> m Caps
- capsCopyNth :: (HasCallStack, MonadIO m) => Caps -> Word32 -> m Caps
- capsFilterAndMapInPlace :: (HasCallStack, MonadIO m) => Caps -> CapsFilterMapFunc -> m ()
- capsFixate :: (HasCallStack, MonadIO m) => Caps -> m Caps
- capsForeach :: (HasCallStack, MonadIO m) => Caps -> CapsForeachFunc -> m Bool
- capsFromString :: (HasCallStack, MonadIO m) => Text -> m (Maybe Caps)
- capsGetFeatures :: (HasCallStack, MonadIO m) => Caps -> Word32 -> m (Maybe CapsFeatures)
- capsGetSize :: (HasCallStack, MonadIO m) => Caps -> m Word32
- capsGetStructure :: (HasCallStack, MonadIO m) => Caps -> Word32 -> m Structure
- capsIntersect :: (HasCallStack, MonadIO m) => Caps -> Caps -> m Caps
- capsIntersectFull :: (HasCallStack, MonadIO m) => Caps -> Caps -> CapsIntersectMode -> m Caps
- capsIsAlwaysCompatible :: (HasCallStack, MonadIO m) => Caps -> Caps -> m Bool
- capsIsAny :: (HasCallStack, MonadIO m) => Caps -> m Bool
- capsIsEmpty :: (HasCallStack, MonadIO m) => Caps -> m Bool
- capsIsEqual :: (HasCallStack, MonadIO m) => Caps -> Caps -> m Bool
- capsIsEqualFixed :: (HasCallStack, MonadIO m) => Caps -> Caps -> m Bool
- capsIsFixed :: (HasCallStack, MonadIO m) => Caps -> m Bool
- capsIsStrictlyEqual :: (HasCallStack, MonadIO m) => Caps -> Caps -> m Bool
- capsIsSubset :: (HasCallStack, MonadIO m) => Caps -> Caps -> m Bool
- capsIsSubsetStructure :: (HasCallStack, MonadIO m) => Caps -> Structure -> m Bool
- capsIsSubsetStructureFull :: (HasCallStack, MonadIO m) => Caps -> Structure -> Maybe CapsFeatures -> m Bool
- capsMapInPlace :: (HasCallStack, MonadIO m) => Caps -> CapsMapFunc -> m Bool
- capsMerge :: (HasCallStack, MonadIO m) => Caps -> Caps -> m Caps
- capsMergeStructure :: (HasCallStack, MonadIO m) => Caps -> Structure -> m Caps
- capsMergeStructureFull :: (HasCallStack, MonadIO m) => Caps -> Structure -> Maybe CapsFeatures -> m Caps
- capsNewAny :: (HasCallStack, MonadIO m) => m Caps
- capsNewEmpty :: (HasCallStack, MonadIO m) => m Caps
- capsNewEmptySimple :: (HasCallStack, MonadIO m) => Text -> m Caps
- capsNormalize :: (HasCallStack, MonadIO m) => Caps -> m Caps
- capsRemoveStructure :: (HasCallStack, MonadIO m) => Caps -> Word32 -> m ()
- capsSerialize :: (HasCallStack, MonadIO m) => Caps -> [SerializeFlags] -> m Text
- capsSetFeatures :: (HasCallStack, MonadIO m) => Caps -> Word32 -> Maybe CapsFeatures -> m ()
- capsSetFeaturesSimple :: (HasCallStack, MonadIO m) => Caps -> Maybe CapsFeatures -> m ()
- capsSetValue :: (HasCallStack, MonadIO m) => Caps -> Text -> GValue -> m ()
- capsSimplify :: (HasCallStack, MonadIO m) => Caps -> m Caps
- capsStealStructure :: (HasCallStack, MonadIO m) => Caps -> Word32 -> m (Maybe Structure)
- capsSubtract :: (HasCallStack, MonadIO m) => Caps -> Caps -> m Caps
- capsToString :: (HasCallStack, MonadIO m) => Caps -> m Text
- capsTruncate :: (HasCallStack, MonadIO m) => Caps -> m Caps
- getCapsMiniObject :: MonadIO m => Caps -> m MiniObject
Exported types
Memory-managed wrapper type.
Instances
Eq Caps Source # | |
GBoxed Caps Source # | |
Defined in GI.Gst.Structs.Caps | |
ManagedPtrNewtype Caps Source # | |
Defined in GI.Gst.Structs.Caps toManagedPtr :: Caps -> ManagedPtr Caps # | |
TypedObject Caps Source # | |
Defined in GI.Gst.Structs.Caps | |
HasParentTypes Caps Source # | |
Defined in GI.Gst.Structs.Caps | |
tag ~ 'AttrSet => Constructible Caps tag Source # | |
Defined in GI.Gst.Structs.Caps | |
IsGValue (Maybe Caps) Source # | Convert |
Defined in GI.Gst.Structs.Caps | |
type ParentTypes Caps Source # | |
Defined in GI.Gst.Structs.Caps |
Methods
Click to display all available methods, including inherited ones
Methods
append, appendStructure, appendStructureFull, canIntersect, copy, copyNth, filterAndMapInPlace, fixate, foreach, intersect, intersectFull, isAlwaysCompatible, isAny, isEmpty, isEqual, isEqualFixed, isFixed, isStrictlyEqual, isSubset, isSubsetStructure, isSubsetStructureFull, mapInPlace, merge, mergeStructure, mergeStructureFull, normalize, removeStructure, serialize, simplify, stealStructure, subtract, toString, truncate.
Getters
getFeatures, getSize, getStructure.
Setters
append
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Caps |
|
-> 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
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Structure |
|
-> m () |
Appends structure
to caps
. The structure is not copied; caps
becomes the owner of structure
.
appendStructureFull
capsAppendStructureFull Source #
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Structure |
|
-> Maybe CapsFeatures |
|
-> m () |
Appends structure
with features
to caps
. The structure is not copied; caps
becomes the owner of structure
.
Since: 1.2
canIntersect
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Caps |
|
-> m Bool | Returns: |
Tries intersecting caps1
and caps2
and reports whether the result would not
be empty
copy
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()
.
copyNth
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Word32 |
|
-> m Caps | Returns: the new |
Creates a new Caps
and appends a copy of the nth structure
contained in caps
.
Since: 1.16
filterAndMapInPlace
capsFilterAndMapInPlace Source #
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> CapsFilterMapFunc |
|
-> 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
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> 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()
.
Note that it is not guaranteed that the returned caps have exactly one
structure. If caps
are empty caps then the returned caps will be
the empty too and contain no structure at all.
Calling this function with ANY caps is not allowed.
foreach
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> CapsForeachFunc |
|
-> m Bool | Returns: |
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
getFeatures
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Word32 |
|
-> m (Maybe CapsFeatures) | Returns: a pointer to the |
Finds the features in caps
at 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 features 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
.
Since: 1.2
getSize
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> m Word32 | Returns: the number of structures that |
Gets the number of structures contained in caps
.
getStructure
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Word32 |
|
-> m Structure | Returns: a pointer to the |
Finds the structure in caps
at 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()
.
intersect
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Caps |
|
-> m Caps | Returns: the new |
Creates a new Caps
that contains all the formats that are common
to both caps1
and caps2
. Defaults to CapsIntersectModeZigZag
mode.
intersectFull
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Caps |
|
-> CapsIntersectMode |
|
-> m Caps | Returns: the new |
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 Source #
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Caps |
|
-> m Bool | Returns: |
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
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> m Bool | Returns: |
Determines if caps
represents any media format.
isEmpty
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> m Bool | Returns: |
Determines if caps
represents no media formats.
isEqual
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Caps |
|
-> m Bool | Returns: |
Checks if the given caps represent the same set of caps.
isEqualFixed
isFixed
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
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Caps |
|
-> m Bool | Returns: |
Checks if the given caps are exactly the same set of caps.
isSubset
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Caps |
|
-> m Bool | Returns: |
Checks if all caps represented by subset
are also represented by superset
.
isSubsetStructure
capsIsSubsetStructure Source #
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Structure |
|
-> m Bool | Returns: |
Checks if structure
is a subset of caps
. See capsIsSubset
for more information.
isSubsetStructureFull
capsIsSubsetStructureFull Source #
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Structure |
|
-> Maybe CapsFeatures |
|
-> m Bool | Returns: |
Checks if structure
is a subset of caps
. See capsIsSubset
for more information.
Since: 1.2
mapInPlace
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> CapsMapFunc |
|
-> m Bool | Returns: |
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
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Caps |
|
-> 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
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Structure |
|
-> m Caps | Returns: the merged caps. |
Appends structure
to caps
if it is not already expressed by caps
.
mergeStructureFull
capsMergeStructureFull Source #
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Structure |
|
-> Maybe CapsFeatures |
|
-> m Caps | Returns: the merged caps. |
Appends structure
with features
to caps
if its not already expressed by caps
.
Since: 1.2
newAny
:: (HasCallStack, MonadIO m) | |
=> m Caps | Returns: the new |
Creates a new Caps
that indicates that it is compatible with
any media format.
newEmpty
:: (HasCallStack, MonadIO m) | |
=> m Caps | Returns: the new |
newEmptySimple
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m Caps | Returns: the new |
normalize
Returns a Caps
that represents the same set of formats as
caps
, but contains no lists. Each list is expanded into separate
Structure
.
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
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Word32 |
|
-> m () |
Removes the structure with the given index from the list of structures
contained in caps
.
serialize
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> [SerializeFlags] |
|
-> m Text | Returns: a newly allocated string representing |
Converts caps
to a string representation. This string representation can be
converted back to a Caps
by capsFromString
.
This prints the caps in human readable form.
This version of the caps serialization function introduces support for nested
structures and caps but the resulting strings won't be parsable with
GStreamer prior to 1.20 unless GST_SERIALIZE_FLAG_BACKWARD_COMPAT
is passed
as flag
.
Since: 1.20
setFeatures
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Word32 |
|
-> Maybe CapsFeatures |
|
-> m () |
Sets the features
for the structure at index
.
Since: 1.2
setFeaturesSimple
capsSetFeaturesSimple Source #
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Maybe CapsFeatures |
|
-> m () |
Sets the features
for all the structures of caps
.
Since: 1.16
setValue
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Text |
|
-> GValue |
|
-> 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
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> 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
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Word32 |
|
-> m (Maybe Structure) | Returns: a pointer to the |
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
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> Caps |
|
-> 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
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> m Text | Returns: a newly allocated string representing |
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
GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
``
This prints the caps in human readable form.
The implementation of serialization up to 1.20 would lead to unexpected results
when there were nested Caps
/ Structure
deeper than one level.
truncate
:: (HasCallStack, MonadIO m) | |
=> Caps |
|
-> m Caps | Returns: truncated caps |
Discards 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()
.
Note that it is not guaranteed that the returned caps have exactly one
structure. If caps
is any or empty caps then the returned caps will be
the same and contain no structure at all.
Properties
miniObject
the parent type
getCapsMiniObject :: MonadIO m => Caps -> m MiniObject Source #
Get the value of the “mini_object
” field.
When overloading is enabled, this is equivalent to
get
caps #miniObject