org.gstreamer

Class Caps

java.lang.Object

org.gstreamer.lowlevel.NativeValue

org.gstreamer.lowlevel.Handle

org.gstreamer.lowlevel.NativeObject

org.gstreamer.lowlevel.RefCountedObject

org.gstreamer.Caps

public class Caps
extends RefCountedObject

Structure describing sets of media formats

Caps (capabilities) are lightweight 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 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(org.gstreamer.Caps). 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.gstreamer.lowlevel.NativeObject

NativeObject.Initializer

Field Summary

Fields

Modifier and Type	Field and Description
static String	GTYPE_NAME

Fields inherited from class org.gstreamer.lowlevel.NativeObject

defaultInit, ownsHandle

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(NativeObject.Initializer init)
Caps(String caps) Construct a new Caps from a string representation.

Method Summary

Methods

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.
protected void	disposeNativeHandle(com.sun.jna.Pointer ptr)
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.
protected static NativeObject.Initializer	initializer(com.sun.jna.Pointer ptr)
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.
void	merge(Caps other) Merge another Caps with this one.
void	merge(Structure structure) Append a structure to this caps.
Caps	normalize() Normalize the Caps.
protected void	ref()
void	removeStructure(int index) Remove a struture from the caps.
void	setInteger(String field, Integer value)
boolean	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()
void	truncate() Destructively discard all but the first structure from this caps.
Caps	union(Caps other) Creates a new Caps that contains all the formats that are in either this Caps or the other Caps.
protected void	unref()

Methods inherited from class org.gstreamer.lowlevel.NativeObject

classFor, disown, dispose, finalize, getNativeAddress, handle, hashCode, initializer, instanceFor, invalidate, isDisposed, nativeValue, objectFor, objectFor, objectFor, objectFor

Methods inherited from class java.lang.Object

clone, 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()

Caps

public Caps(NativeObject.Initializer init)

Method Detail

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.

anyCaps

public static Caps anyCaps()

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

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-rgb, bpp=32, depth=24, width=640, height=480");

Parameters:

caps - The string representation of the caps.

Returns:

The new Caps.

initializer

protected static NativeObject.Initializer initializer(com.sun.jna.Pointer ptr)

size

public int size()

Get the number of structures contained in this caps.

Returns:

the number of structures that this caps contains

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.

Returns:

The new Caps.

union

public Caps union(Caps other)

Creates a new Caps that contains all the formats that are in either this Caps or the other Caps.

Parameters:

other - The Caps to union with this one.

Returns:

The new Caps

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

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.

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

simplify

public boolean 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:

true if the caps could be simplified

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.

removeStructure

public void removeStructure(int index)

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

Parameters:

index - Index of the structure to remove.

merge

public void merge(Caps other)

Merge another Caps with this one.

Appends the structures contained in the other Caps to this one, if they are not yet expressed by this Caps.

The structures in other are not copied, they are transferred to this Caps, and then other is freed.

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

Do not use the argument after calling this method, as the native peer is no longer valid.

Parameters:

other - The other Caps to merge.

merge

public void merge(Structure structure)

Append a structure to this caps. Appends structure to this caps if its not already expressed. The structure is not copied; caps becomes the owner of structure and structure must not be used after calling this method.

Parameters:

structure - The structure to merge.

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.

Returns:

A writable version of this caps object.

setInteger

public void setInteger(String field,
              Integer value)

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.

truncate

public void truncate()

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

toString

public String toString()

Overrides:

toString in class NativeObject

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.

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

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.

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

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.

equals

public boolean equals(Object other)

Overrides:

equals in class NativeObject

ref

protected void ref()

Specified by:

ref in class RefCountedObject

unref

protected void unref()

Specified by:

unref in class RefCountedObject

disposeNativeHandle

protected void disposeNativeHandle(com.sun.jna.Pointer ptr)

Specified by:

disposeNativeHandle in class NativeObject