org.freedesktop.gstreamer

Class Caps

java.lang.Object

org.freedesktop.gstreamer.glib.NativeObject

org.freedesktop.gstreamer.glib.RefCountedObject

org.freedesktop.gstreamer.MiniObject

org.freedesktop.gstreamer.Caps

All Implemented Interfaces:

AutoCloseable

public class Caps
extends MiniObject

Structure describing sets of media formats

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

See upstream documentation at https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstCaps.html

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 Pad#getCaps method. This method describes the possible types that the pad can handle or produce at runtime.

Caps are also attached to buffers to describe the content of the data pointed to by the buffer with Buffer#setCaps. Caps attached to a Buffer allow for format negotiation upstream and downstream.

A Caps can be constructed with the following code fragment:

Caps caps = Caps.fromString("video/x-raw-rgb, bpp=32, depth=24, width=640, height=480");

A Caps is fixed when it has no properties with ranges or lists. Use isFixed() to test for fixed caps. Only fixed caps can be set on a Pad or Buffer.

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

See Also:

Structure

Nested Class Summary

Nested classes/interfaces inherited from class org.freedesktop.gstreamer.glib.NativeObject

NativeObject.Initializer, NativeObject.TypeProvider, NativeObject.TypeRegistration<T extends NativeObject>

Field Summary

Fields

Modifier and Type	Field and Description
static String	GTYPE_NAME

Constructor Summary

Constructors

Constructor and Description
Caps() Creates a new Caps that is empty.
Caps(Caps caps) Create a caps that is a copy of another caps.
Caps(String caps) Construct a new Caps from a string representation.

Method Summary

Modifier and Type	Method and Description
static Caps	anyCaps() Creates a new Caps that indicates that it is compatible with any media format.
void	append(Caps caps) Append the structures contained in caps to this caps object.
void	append(Structure struct) Append structure to this caps.
Caps	copy() Create a new Caps as a copy of the this caps.
static Caps	emptyCaps() Creates a new Caps that is empty.
boolean	equals(Object other)
static Caps	fromString(String caps) Construct a new Caps from a string representation.
Structure	getStructure(int index) Get a Structure contained in this caps.
Caps	intersect(Caps other) Creates a new Caps that contains all the formats that are common to both this Caps and the other Caps.
boolean	isAlwaysCompatible(Caps other) Check if this caps is always compatible with another caps.
boolean	isAny() Determine if this caps represents any media format.
boolean	isEmpty() Determine if this caps represents no media formats.
boolean	isEqual(Caps other) Checks if the given caps represent the same set of caps.
boolean	isEqualFixed(Caps other) Tests if two Caps are equal.
boolean	isFixed() Determine if this caps is fixed.
boolean	isSubset(Caps superset) Checks if all caps represented by this caps are also represented by superset.
Caps	makeWritable() Returns a writable copy of this caps.
static Caps	merge(Caps caps1, Caps caps2) Merge two Caps together.
Caps	normalize() Normalize the Caps.
void	removeStructure(int index) Remove a structure from the caps.
void	setInteger(String field, Integer value)
Caps	simplify() Modifies this caps inplace into a representation that represents the same set of formats, but in a simpler form.
int	size() Get the number of structures contained in this caps.
Caps	subtract(Caps subtrahend) Subtracts the subtrahend Caps from this Caps.
String	toString()
Caps	truncate() Destructively discard all but the first structure from this caps.

Methods inherited from class org.freedesktop.gstreamer.MiniObject

getRefCount, isWritable

Methods inherited from class org.freedesktop.gstreamer.glib.NativeObject

close, disown, dispose, getPointer, getRawPointer, hashCode, invalidate

Methods inherited from class java.lang.Object

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

Field Detail

GTYPE_NAME

public static final String GTYPE_NAME

See Also:

Constant Field Values

Constructor Detail

Caps

public Caps()

Creates a new Caps that is empty. That is, the returned Caps contains no media formats.

See Also:

emptyCaps()

Caps

public Caps(String caps)

Construct a new Caps from a string representation.

Parameters:

caps - The string representation of the caps.

See Also:

fromString(java.lang.String)

Caps

public Caps(Caps caps)

Create a caps that is a copy of another caps.

Parameters:

caps - The caps to copy.

See Also:

copy()

Method Detail

append

public void append(Caps caps)

Append the structures contained in caps to this caps object. The structures in caps are not copied -- they are transferred to this caps.

If either caps is ANY, the resulting caps will be ANY.

Parameters:

caps - The Caps to append

append

public void append(Structure struct)

Append structure to this caps. The structure is not copied; this caps takes ownership, so do not use struct after calling this method.

Parameters:

struct - The structure to append.

copy

public Caps copy()

Create a new Caps as a copy of the this caps. The new Caps will be a copy of this caps, with all the internal structures copied as well.

Overrides:

copy in class MiniObject

Returns:

The new Caps.

equals

public boolean equals(Object other)

Overrides:

equals in class NativeObject

getStructure

public Structure getStructure(int index)

Get a Structure contained in this caps. Finds the structure in @caps that has the index @index, and returns it.

Parameters:

index - The index of the structure to get.

Returns:

The Structure corresponding to index.

intersect

public Caps intersect(Caps other)

Creates a new Caps that contains all the formats that are common to both this Caps and the other Caps.

Parameters:

other - The Caps to intersect with this one.

Returns:

The new Caps

isAlwaysCompatible

public boolean isAlwaysCompatible(Caps other)

Check if this caps is always compatible with another caps.

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, this caps1 is a subset of other.

Parameters:

other - The caps to test against.

Returns:

true if other is always compatible with this caps.

isAny

public boolean isAny()

Determine if this caps represents any media format.

Returns:

true if this caps represents any format.

isEmpty

public boolean isEmpty()

Determine if this caps represents no media formats.

Returns:

true if this caps represents no formats.

isEqual

public boolean isEqual(Caps other)

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

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

Parameters:

other - The caps to compare this caps to.

Returns:

true if other caps equals this one.

isEqualFixed

public boolean isEqualFixed(Caps other)

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

Parameters:

other - The other caps to test against.

Returns:

true if the other caps is equal to this one.

isFixed

public boolean isFixed()

Determine if this 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.

Returns:

true if this caps is fixed

isSubset

public boolean isSubset(Caps superset)

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

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

Parameters:

superset - The potentially greater Caps

Returns:

true if this caps is a subset of superset

makeWritable

public Caps makeWritable()

Returns a writable copy of this caps.

This method will invalidate the native side of this caps object, so it should not be used after calling this method, and only the returned Caps object should be used.

Overrides:

makeWritable in class MiniObject

Returns:

A writable version of this caps object.

normalize

public Caps normalize()

Normalize the Caps. Creates a new Caps that represents the same set of formats as this Caps, but contains no lists. Each list is expanded into separate Structures

Returns:

The new Caps

See Also:

Structure

removeStructure

public void removeStructure(int index)

Remove a structure from the caps. Removes the structure with the given index from the list of structures contained in this caps.

Parameters:

index - Index of the structure to remove.

setInteger

public void setInteger(String field,
                       Integer value)

simplify

public Caps simplify()

Modifies this 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.

Returns:

The new Caps

size

public int size()

Get the number of structures contained in this caps.

Returns:

the number of structures that this caps contains

subtract

public Caps subtract(Caps subtrahend)

Subtracts the subtrahend Caps from 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 - The Caps to subtract.

Returns:

The resulting caps.

toString

public String toString()

Overrides:

toString in class NativeObject

truncate

public Caps truncate()

Destructively discard all but the first structure from this caps. Useful when fixating. This caps must be writable.

Returns:

truncated copy of the Caps

anyCaps

public static Caps anyCaps()

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

Returns:

The new Caps.

emptyCaps

public static Caps emptyCaps()

Creates a new Caps that is empty. That is, the returned Caps contains no media formats.

Returns:

The new Caps.

fromString

public static Caps fromString(String caps)

Construct a new Caps from a string representation. Example:

Caps caps = Caps.fromString("video/x-raw, format=RGB, bpp=32, depth=24, width=640, height=480");

Parameters:

caps - The string representation of the caps.

Returns:

The new Caps.

merge

public static Caps merge(Caps caps1,
                         Caps caps2)

Merge two Caps together.

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.

Parameters:

caps1 - the Caps that will take the new entries.

caps2 - the Caps to merge in

Returns:

merged Caps