org.gstreamer
Class Caps

java.lang.Object
  extended by org.gstreamer.lowlevel.NativeValue
      extended by org.gstreamer.lowlevel.Handle
          extended by org.gstreamer.lowlevel.NativeObject
              extended by org.gstreamer.lowlevel.RefCountedObject
                  extended by org.gstreamer.Caps

public class Caps
extends org.gstreamer.lowlevel.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
org.gstreamer.lowlevel.NativeObject.Initializer
 
Field Summary
 
Fields inherited from class org.gstreamer.lowlevel.NativeObject
defaultInit, LIFECYCLE, ownsHandle
 
Constructor Summary
Caps()
          Creates a new Caps that is empty.
Caps(Caps caps)
          Create a caps that is a copy of another caps.
Caps(org.gstreamer.lowlevel.NativeObject.Initializer init)
           
Caps(java.lang.String caps)
          Construct a new Caps from a string representation.
 
Method Summary
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(java.lang.Object other)
           
static Caps fromString(java.lang.String caps)
          Construct a new Caps from a string representation.
 Structure getStructure(int index)
          Get a Structure contained in this caps.
protected static org.gstreamer.lowlevel.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(java.lang.String field, java.lang.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.
 java.lang.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
 
Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, wait, wait, wait
 

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(java.lang.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(org.gstreamer.lowlevel.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(java.lang.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 org.gstreamer.lowlevel.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(java.lang.String field,
                       java.lang.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 java.lang.String toString()
Overrides:
toString in class org.gstreamer.lowlevel.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(java.lang.Object other)
Overrides:
equals in class org.gstreamer.lowlevel.NativeObject

ref

protected void ref()
Specified by:
ref in class org.gstreamer.lowlevel.RefCountedObject

unref

protected void unref()
Specified by:
unref in class org.gstreamer.lowlevel.RefCountedObject

disposeNativeHandle

protected void disposeNativeHandle(com.sun.jna.Pointer ptr)
Specified by:
disposeNativeHandle in class org.gstreamer.lowlevel.NativeObject