Package org.freedesktop.gstreamer.gst

Class Caps

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.freedesktop.gstreamer.gst.Caps

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class Caps
extends ProxyInstance

Caps (capabilities) are lightweight 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_query_caps() pad function. This function describes the possible types that the pad can handle or produce at runtime.

A GstCaps can be constructed with the following code fragment:

  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 GstCaps is fixed when it has no fields with ranges or lists. Use gst_caps_is_fixed() 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 GstCaps / GstStructure serialization into string had limited support for nested GstCaps / GstStructure fields. It could only support one level of nesting. Using more levels would lead to unexpected behavior when using serialization features, such as gst_caps_to_string() or gst_value_serialize() and their counterparts.

Constructor Summary

Constructors

Constructor	Description
Caps()	Allocate a new Caps.
Caps(Arena arena)	Allocate a new Caps.
Caps(MemorySegment address)	Create a Caps proxy instance for the provided memory address.
Caps(MiniObject miniObject)	Allocate a new Caps with the fields set to the provided values.
Caps(MiniObject miniObject, Arena arena)	Allocate a new Caps with the fields set to the provided values.

Method Summary

Modifier and Type	Method	Description
static Caps	any()	Creates a new GstCaps that indicates that it is compatible with any media format.
void	append(Caps caps2)	Appends the structures contained in caps2 to this Caps.
void	appendStructure(Structure structure)	Appends structure to this Caps.
void	appendStructureFull(Structure structure, @Nullable CapsFeatures features)	Appends structure with features to this Caps.
boolean	canIntersect(Caps caps2)	Tries intersecting this Caps and caps2 and reports whether the result would not be empty
Caps	copy()	Creates a new GstCaps as a copy of the old this Caps.
Caps	copyNth(int nth)	Creates a new GstCaps and appends a copy of the nth structure contained in this Caps.
static Caps	empty()	Creates a new GstCaps that is empty.
static Caps	emptySimple(String mediaType)	Creates a new GstCaps that contains one GstStructure with name mediaType.
void	filterAndMapInPlace(CapsFilterMapFunc func)	Calls the provided function once for each structure and caps feature in the GstCaps.
Caps	fixate()	Modifies the given this Caps into a representation with only fixed values.
boolean	foreach(CapsForeachFunc func)	Calls the provided function once for each structure and caps feature in the GstCaps.
static Caps	fromString(String string)	Converts caps from a string representation.
static Caps	full(Structure struct1, Object... varargs)	Creates a new GstCaps and adds all the structures listed as arguments.
CapsFeatures	getFeatures(int index)	Finds the features in this Caps at index, and returns it.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
int	getSize()	Gets the number of structures contained in this Caps.
Structure	getStructure(int index)	Finds the structure in this Caps at index, and returns it.
static Type	getType()	Get the GType of the Caps class
Caps	intersect(Caps caps2)	Creates a new GstCaps that contains all the formats that are common to both this Caps and caps2.
Caps	intersectFull(Caps caps2, CapsIntersectMode mode)	Creates a new GstCaps that contains all the formats that are common to both this Caps and caps2, the order is defined by the GstCapsIntersectMode used.
boolean	isAlwaysCompatible(Caps caps2)	A given GstCaps structure is always compatible with another if every media format that is in the first is also contained in the second.
boolean	isAny()	Determines if this Caps represents any media format.
boolean	isEmpty()	Determines if this Caps represents no media formats.
boolean	isEqual(Caps caps2)	Checks if the given caps represent the same set of caps.
boolean	isEqualFixed(Caps caps2)	Tests if two GstCaps are equal.
boolean	isFixed()	Fixed GstCaps describe exactly one format, that is, they have exactly one structure, and each field in the structure describes a fixed type.
boolean	isStrictlyEqual(Caps caps2)	Checks if the given caps are exactly the same set of caps.
boolean	isSubset(Caps superset)	Checks if all caps represented by this Caps are also represented by superset.
boolean	isSubsetStructure(Structure structure)	Checks if structure is a subset of this Caps.
boolean	isSubsetStructureFull(Structure structure, @Nullable CapsFeatures features)	Checks if structure is a subset of this Caps.
boolean	mapInPlace(CapsMapFunc func)	Calls the provided function once for each structure and caps feature in the GstCaps.
Caps	merge(Caps caps2)	Appends the structures contained in caps2 to this Caps if they are not yet expressed by this Caps.
Caps	mergeStructure(Structure structure)	Appends structure to this Caps if it is not already expressed by this Caps.
Caps	mergeStructureFull(Structure structure, @Nullable CapsFeatures features)	Appends structure with features to this Caps if its not already expressed by this Caps.
Caps	normalize()	Returns a GstCaps that represents the same set of formats as this Caps, but contains no lists.
MiniObject	readMiniObject()	Read the value of the field mini_object.
Caps	ref()	Adds a reference to a GstCaps object.
void	removeStructure(int idx)	Removes the structure with the given index from the list of structures contained in this Caps.
static boolean	replace(@Nullable Out<Caps> oldCaps, @Nullable Caps newCaps)	Modifies a pointer to a GstCaps to point to a different GstCaps.
String	serialize(Set<SerializeFlags> flags)	Converts this Caps to a string representation.
String	serialize(SerializeFlags... flags)	Converts this Caps to a string representation.
void	setFeatures(int index, @Nullable CapsFeatures features)	Sets the features for the structure at index.
void	setFeaturesSimple(@Nullable CapsFeatures features)	Sets the features for all the structures of this Caps.
void	setSimple(String field, Object... varargs)	Sets fields in a GstCaps.
void	setValue(String field, Value value)	Sets the given field on all structures of this Caps to the given value.
static Caps	simple(String mediaType, String fieldname, Object... varargs)	Creates a new GstCaps that contains one GstStructure.
Caps	simplify()	Converts the given this Caps into a representation that represents the same set of formats, but in a simpler form.
Structure	stealStructure(int index)	Retrieves the structure with the given index from the list of structures contained in this Caps.
Caps	subtract(Caps subtrahend)	Subtracts the subtrahend from the this Caps.
static boolean	take(Out<Caps> oldCaps, @Nullable Caps newCaps)	Modifies a pointer to a GstCaps to point to a different GstCaps.
String	toString()	Converts this Caps to a string representation.
Caps	truncate()	Discards all but the first structure from this Caps.
void	unref()	Unrefs a GstCaps and frees all its structures and the structures' values when the refcount reaches 0.
void	writeMiniObject(MiniObject miniObject)	Write a value in the field mini_object.

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Details

Caps

public Caps(MemorySegment address)

Create a Caps proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Caps

public Caps(Arena arena)

Allocate a new Caps.

Parameters:

arena - to control the memory allocation scope

Caps

public Caps()

Allocate a new Caps. The memory is allocated with Arena.ofAuto().

Caps

public Caps(MiniObject miniObject,
 Arena arena)

Allocate a new Caps with the fields set to the provided values.

Parameters:

miniObject - value for the field miniObject

arena - to control the memory allocation scope

Caps

public Caps(MiniObject miniObject)

Allocate a new Caps with the fields set to the provided values. The memory is allocated with Arena.ofAuto().

Parameters:

miniObject - value for the field miniObject

Method Details

getType

public static Type getType()

Get the GType of the Caps class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

readMiniObject

public MiniObject readMiniObject()

Read the value of the field mini_object.

Returns:

The value of the field mini_object

writeMiniObject

public void writeMiniObject(MiniObject miniObject)

Write a value in the field mini_object.

Parameters:

miniObject - The new value for the field mini_object

any

public static Caps any()

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

Returns:

the new GstCaps

empty

public static Caps empty()

Creates a new GstCaps that is empty. That is, the returned GstCaps contains no media formats. The GstCaps is guaranteed to be writable.

Returns:

the new GstCaps

emptySimple

public static Caps emptySimple(String mediaType)

Creates a new GstCaps that contains one GstStructure with name mediaType.

Parameters:

mediaType - the media type of the structure

Returns:

the new GstCaps

full

public static Caps full(Structure struct1,
 Object... varargs)

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.

Parameters:

struct1 - the first structure to add

varargs - additional structures to add

Returns:

the new GstCaps

simple

public static Caps simple(String mediaType,
 String fieldname,
 Object... varargs)

Creates a new GstCaps that contains one GstStructure. The structure is defined by the arguments, which have the same format as gst_structure_new().

Parameters:

mediaType - the media type of the structure

fieldname - first field to set

varargs - additional arguments

Returns:

the new GstCaps

fromString

public static Caps fromString(String string)

Converts caps from a string representation.

The implementation of serialization up to 1.20 would lead to unexpected results when there were nested GstCaps / GstStructure deeper than one level.

Parameters:

string - a string to convert to GstCaps

Returns:

a newly allocated GstCaps

replace

public static boolean replace(@Nullable
 @Nullable Out<Caps> oldCaps,
 @Nullable
 @Nullable Caps newCaps)

Modifies a pointer to a GstCaps to point to a different GstCaps. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old caps is unreffed, the new is reffed).

Either newCaps or the GstCaps pointed to by oldCaps may be null.

Parameters:

oldCaps - pointer to a pointer to a GstCaps to be replaced.

newCaps - pointer to a GstCaps that will replace the caps pointed to by oldCaps.

Returns:

true if newCaps was different from oldCaps

take

public static boolean take(Out<Caps> oldCaps,
 @Nullable
 @Nullable Caps newCaps)

Modifies a pointer to a GstCaps to point to a different GstCaps. This function is similar to gst_caps_replace() except that it takes ownership of newCaps.

Parameters:

oldCaps - pointer to a pointer to a GstCaps to be replaced.

newCaps - pointer to a GstCaps that will replace the caps pointed to by oldCaps.

Returns:

true if newCaps was different from oldCaps

append

public void append(Caps caps2)

Appends the structures contained in caps2 to this Caps. The structures in caps2 are not copied -- they are transferred to this Caps, and then caps2 is freed. If either caps is ANY, the resulting caps will be ANY.

Parameters:

caps2 - the GstCaps to append

appendStructure

public void appendStructure(Structure structure)

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

Parameters:

structure - the GstStructure to append

appendStructureFull

public void appendStructureFull(Structure structure,
 @Nullable
 @Nullable CapsFeatures features)

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

Parameters:

structure - the GstStructure to append

features - the GstCapsFeatures to append

canIntersect

public boolean canIntersect(Caps caps2)

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

Parameters:

caps2 - a GstCaps to intersect

Returns:

true if intersection would be not empty

copy

public Caps copy()

Creates a new GstCaps as a copy of the old this 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().

Returns:

the new GstCaps

copyNth

public Caps copyNth(int nth)

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

Parameters:

nth - the nth structure to copy

Returns:

the new GstCaps

filterAndMapInPlace

public void filterAndMapInPlace(CapsFilterMapFunc func)

Calls the provided function once for each structure and caps feature in the GstCaps. In contrast to gst_caps_foreach(), the function may modify the structure and features. In contrast to gst_caps_map_in_place(), the structure and features are removed from the caps if false is returned from the function. The caps must be mutable.

Parameters:

func - a function to call for each field

fixate

public Caps fixate()

Modifies the given this Caps into a representation with only fixed values. First the caps will be truncated and then the first structure will be fixated with gst_structure_fixate().

This function takes ownership of this Caps and will call gst_caps_make_writable() on it so you must not use this 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 this 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.

Returns:

the fixated caps

foreach

public boolean foreach(CapsForeachFunc func)

Calls the provided function once for each structure and caps feature in the GstCaps. The function must not modify the fields. Also see gst_caps_map_in_place() and gst_caps_filter_and_map_in_place().

Parameters:

func - a function to call for each field

Returns:

true if the supplied function returns true for each call, false otherwise.

getFeatures

public CapsFeatures getFeatures(int index)

Finds the features in this 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 GstCaps 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 gst_caps_features_add().

Parameters:

index - the index of the structure

Returns:

a pointer to the GstCapsFeatures corresponding to index

getSize

public int getSize()

Gets the number of structures contained in this Caps.

Returns:

the number of structures that this Caps contains

getStructure

public Structure getStructure(int index)

Finds the structure in this 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 GstCaps 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().

Parameters:

index - the index of the structure

Returns:

a pointer to the GstStructure corresponding to index

intersect

public Caps intersect(Caps caps2)

Creates a new GstCaps that contains all the formats that are common to both this Caps and caps2. Defaults to CapsIntersectMode.ZIG_ZAG mode.

Parameters:

caps2 - a GstCaps to intersect

Returns:

the new GstCaps

intersectFull

public Caps intersectFull(Caps caps2,
 CapsIntersectMode mode)

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

Parameters:

caps2 - a GstCaps to intersect

mode - The intersection algorithm/mode to use

Returns:

the new GstCaps

isAlwaysCompatible

public boolean isAlwaysCompatible(Caps caps2)

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, this Caps is a subset of caps2.

Parameters:

caps2 - the GstCaps to test

Returns:

true if this Caps is a subset of caps2.

isAny

public boolean isAny()

Determines if this Caps represents any media format.

Returns:

true if this Caps represents any format.

isEmpty

public boolean isEmpty()

Determines if this Caps represents no media formats.

Returns:

true if this Caps represents no formats.

isEqual

public boolean isEqual(Caps caps2)

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

Parameters:

caps2 - another GstCaps

Returns:

true if both caps are equal.

isEqualFixed

public boolean isEqualFixed(Caps caps2)

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

Parameters:

caps2 - the GstCaps to test

Returns:

true if the arguments represent the same format

isFixed

public boolean isFixed()

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.

Returns:

true if this Caps is fixed

isStrictlyEqual

public boolean isStrictlyEqual(Caps caps2)

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

Parameters:

caps2 - another GstCaps

Returns:

true if both caps are strictly equal.

isSubset

public boolean isSubset(Caps superset)

Checks if all caps represented by this Caps are also represented by superset.

Parameters:

superset - a potentially greater GstCaps

Returns:

true if this Caps is a subset of superset

isSubsetStructure

public boolean isSubsetStructure(Structure structure)

Checks if structure is a subset of this Caps. See gst_caps_is_subset() for more information.

Parameters:

structure - a potential GstStructure subset of this Caps

Returns:

true if structure is a subset of this Caps

isSubsetStructureFull

public boolean isSubsetStructureFull(Structure structure,
 @Nullable
 @Nullable CapsFeatures features)

Checks if structure is a subset of this Caps. See gst_caps_is_subset() for more information.

Parameters:

structure - a potential GstStructure subset of this Caps

features - a GstCapsFeatures for structure

Returns:

true if structure is a subset of this Caps

mapInPlace

public boolean mapInPlace(CapsMapFunc func)

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

Parameters:

func - a function to call for each field

Returns:

true if the supplied function returns true for each call, false otherwise.

merge

public Caps merge(Caps caps2)

Appends the structures contained in caps2 to this Caps if they are not yet expressed by this Caps. The structures in caps2 are not copied -- they are transferred to a writable copy of this Caps, and then caps2 is freed. If either caps is ANY, the resulting caps will be ANY.

Parameters:

caps2 - the GstCaps to merge in

Returns:

the merged caps.

mergeStructure

public Caps mergeStructure(Structure structure)

Appends structure to this Caps if it is not already expressed by this Caps.

Parameters:

structure - the GstStructure to merge

Returns:

the merged caps.

mergeStructureFull

public Caps mergeStructureFull(Structure structure,
 @Nullable
 @Nullable CapsFeatures features)

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

Parameters:

structure - the GstStructure to merge

features - the GstCapsFeatures to merge

Returns:

the merged caps.

normalize

public Caps normalize()

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

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

Returns:

the normalized GstCaps

ref

public Caps ref()

Adds 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 e.g. gst_caps_new_simple(), or via taking one explicitly with this function.

Returns:

the same GstCaps object.

removeStructure

public void removeStructure(int idx)

Removes the structure with the given index from the list of structures contained in this Caps.

Parameters:

idx - Index of the structure to remove

serialize

public String serialize(Set<SerializeFlags> flags)

Converts this Caps to a string representation. This string representation can be converted back to a GstCaps by gst_caps_from_string().

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.

Parameters:

flags - a GstSerializeFlags

Returns:

a newly allocated string representing this Caps.

serialize

public String serialize(SerializeFlags... flags)

Converts this Caps to a string representation. This string representation can be converted back to a GstCaps by gst_caps_from_string().

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.

Parameters:

flags - a GstSerializeFlags

Returns:

a newly allocated string representing this Caps.

setFeatures

public void setFeatures(int index,
 @Nullable
 @Nullable CapsFeatures features)

Sets the features for the structure at index.

Parameters:

index - the index of the structure

features - the GstCapsFeatures to set

setFeaturesSimple

public void setFeaturesSimple(@Nullable
 @Nullable CapsFeatures features)

Sets the features for all the structures of this Caps.

Parameters:

features - the GstCapsFeatures to set

setSimple

public void setSimple(String field,
 Object... varargs)

Sets fields in a GstCaps. The arguments must be passed in the same manner as gst_structure_set(), and be null-terminated.

Parameters:

field - first field to set

varargs - additional parameters

setValue

public void setValue(String field,
 Value value)

Sets the given field on all structures of this Caps to the given value. This is a convenience function for calling gst_structure_set_value() on all structures of this Caps.

Parameters:

field - name of the field to set

value - value to set the field to

simplify

public Caps simplify()

Converts the given this 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 this Caps and will call gst_caps_make_writable() on it if necessary, so you must not use this Caps afterwards unless you keep an additional reference to it with gst_caps_ref().

This method does not preserve the original order of this Caps.

Returns:

The simplified caps.

stealStructure

public Structure stealStructure(int index)

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

Parameters:

index - Index of the structure to retrieve

Returns:

a pointer to the GstStructure corresponding to index.

subtract

public Caps subtract(Caps subtrahend)

Subtracts the subtrahend from the this Caps.

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

Parameters:

subtrahend - GstCaps to subtract

Returns:

the resulting caps

toString

public String toString()

Converts this 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 readable form.

The implementation of serialization up to 1.20 would lead to unexpected results when there were nested GstCaps / GstStructure deeper than one level.

Overrides:

toString in class Object

Returns:

a newly allocated string representing this Caps.

truncate

public Caps truncate()

Discards all but the first structure from this Caps. Useful when fixating.

This function takes ownership of this Caps and will call gst_caps_make_writable() on it if necessary, so you must not use this 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 this Caps is any or empty caps then the returned caps will be the same and contain no structure at all.

Returns:

truncated caps

unref

public void unref()

Unrefs a GstCaps and frees all its structures and the structures' values when the refcount reaches 0.