de.humatic.dsj
Class DSFilterInfo

java.lang.Object
  de.humatic.dsj.DSFilterInfo

All Implemented Interfaces:

java.lang.Comparable

Direct Known Subclasses:

EffectDescription

public class DSFilterInfo
extends java.lang.Object
implements java.lang.Comparable

DSFilterInfo wraps a descriptive structure around DirectShow filters. It does not necessarily relate to an initialized instance of the described filter. DSFilterInfos are constructed during device and filter queries and are then used when adding filters to the filtergraph and configuring them, i.e. constructiong DSFilter instances. So: a DSFilter has a DSFilterInfo, but a DSFilterInfo need not have any active filter backing.
Important: Do not try to longterm cache DSFilterInfo objects. When filters are added to the filtergraph dsj may internally reset the FilterInfo in order to be able to reflect the current state (some pins may only be available when a filter's input pin has been connected for example).
Some of the nested classes will only be available for specific filter types.

Nested Class Summary

class	DSFilterInfo.DSCrossBarInfo DSCrossBarInfo represents a capture device's crossbar, which is used to hardware-internally connect inputs to outputs on multi analogue IO devices like combined TV / analogue video capture boards.
class	DSFilterInfo.DSMediaFormat DSMediaFormat represents a mediaformat a specific pin can deliver.
class	DSFilterInfo.DSPinInfo DSPinInfo represents a filter input or output ("Pin" in DirectShow terminology).
class	DSFilterInfo.DSTVTunerInfo DSTVTunerInfo describes the TVTuner interface a Capture Device may expose.

Field Summary

static int	BFRAME Codec configuration paramters
static int	CAPTURE_AUDIO
static int	CAPTURE_DV
static int	CAPTURE_MPEG
static int	CAPTURE_VIDEO
static int	CRUNCH Codec configuration paramters
static int	DO_NOT_USE
static int	IAMVideoCompression Interface types
boolean	isDescriptive
static int	KEYFRAME Codec configuration paramters
static int	QUALITY Codec configuration paramters
static int	SHOW_DLG_SAVE
static int	SHOW_USER_DIALOG

Constructor Summary

DSFilterInfo(java.lang.String name, java.lang.String cid)

Method Summary

int	compareTo(java.lang.Object dsfi)
static DSFilterInfo	createFileInfo(java.lang.String filePath) Creates a fake filterInfo for a media file.
static DSFilterInfo	doNotRender() Static constructor for a dummy info object, that can be passed to class constructors to explicitely NOT render anything.
static DSFilterInfo	filterInfoForCLSID(java.lang.String CLSID) Returns a DSFilterInfo for a filter whose CLSID matches the String argument.
static DSFilterInfo	filterInfoForCodecState(java.lang.String codecName, java.io.File savedState) Creates a FilterInfo for the registered filter with the given name and enables reconfiguration of the filter to the saved state.
static DSFilterInfo	filterInfoForCodecState(java.lang.String filterName, java.lang.String hexData) Creates a FilterInfo for the filter with name %filterName and enables reconfiguration to the filterstate given in the hexstring.
static DSFilterInfo	filterInfoForDll(java.lang.String fullDllPath, java.lang.String CLSID) Creates a FilterInfo for an unregistered DirectShow filter "contained" in the given .dll or .ax file.
static DSFilterInfo	filterInfoForName(java.lang.String name) Returns a DSFilterInfo whose name matches the String argument.
static DSFilterInfo	filterInfoForProfile(java.io.File prx) Creates a "non standard" FilterInfo from a Windows Media profile file (.prx) as written by Windows Media Profile Editor.
static DSFilterInfo	filterInfoForProfile(java.lang.String rawPrx) Creates a "non standard" FilterInfo from a Windows Media profile in raw xml form.
static DSFilterInfo	filterInfoForSystemProfile(int index) Creates a "non standard" FilterInfo for a predefined Windows Media 8 system profile for use as a VideoCompressor parameter in all dsj nethods that write wmv or asf. System profiles are the ones that also show up in the properties dialog of the WM encoders.
java.lang.String	getCLSID()
DSFilterInfo.DSCrossBarInfo	getCrossBarInfo() Returns the crossbar info on analogue video & TV capture devices or null
java.lang.String	getDllLocation() Returns the location of the .ax.
DSFilterInfo.DSPinInfo[]	getDownstreamPins() Gets a filters outputs
java.lang.String	getName()
java.lang.String	getPath()
DSFilterInfo.DSPinInfo[]	getPins() Gets all inputs and outputs
int	getPreferredFormat()
java.lang.String	getSubGUID()
DSFilterInfo.DSTVTunerInfo	getTVTunerInfo() Returns the TVTuner info on TV devices or null
int	getType() Deprecated. method, getType() is deprecated. This was previously used to categorize capture devices. Examine the output formats to do so.
DSFilterInfo.DSPinInfo[]	getUpstreamPins() Gets a filters inputs
boolean	isNullInfo() Returns true for "doNotRender()" DSFilterinfos.
boolean	resolve() DSFilterInfos may have varying informational depth, depending on how they were constructed and whether they belong to a DSFilter in a filtergraph.
void	setPreferredFormat(int fIndex) Used to make DirectShow render at a specific format when constructing a filter instance with a DSFilterInfo argument.
java.lang.String	toString() Returns an informative String, containing info about the described filter, its pins and their formats

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

SHOW_USER_DIALOG

public static final int SHOW_USER_DIALOG

See Also:

Constant Field Values

SHOW_DLG_SAVE

public static final int SHOW_DLG_SAVE

See Also:

Constant Field Values

DO_NOT_USE

public static final int DO_NOT_USE

See Also:

Constant Field Values

CAPTURE_VIDEO

public static final int CAPTURE_VIDEO

See Also:

Constant Field Values

CAPTURE_AUDIO

public static final int CAPTURE_AUDIO

See Also:

Constant Field Values

CAPTURE_MPEG

public static final int CAPTURE_MPEG

See Also:

Constant Field Values

CAPTURE_DV

public static final int CAPTURE_DV

See Also:

Constant Field Values

IAMVideoCompression

public static final int IAMVideoCompression

Interface types

See Also:

Constant Field Values

QUALITY

public static final int QUALITY

Codec configuration paramters

See Also:

Constant Field Values

CRUNCH

public static final int CRUNCH

Codec configuration paramters

See Also:

Constant Field Values

KEYFRAME

public static final int KEYFRAME

Codec configuration paramters

See Also:

Constant Field Values

BFRAME

public static final int BFRAME

Codec configuration paramters

See Also:

Constant Field Values

isDescriptive

public boolean isDescriptive

Constructor Detail

DSFilterInfo

public DSFilterInfo(java.lang.String name,
                    java.lang.String cid)

Method Detail

doNotRender

public static DSFilterInfo doNotRender()

Static constructor for a dummy info object, that can be passed to class constructors to explicitely NOT render anything. (Usually passing null as an argument instructs DirectShow to fall back on defaults.)

filterInfoForName

public static DSFilterInfo filterInfoForName(java.lang.String name)
                                      throws DSJException

Returns a DSFilterInfo whose name matches the String argument. This queries for filters internally and will fail if the filter refered to has not been registered with COM during its installation or by using regsvr32 manually. Throws DSJException if no filter with the given name is found.

Throws:

DSJException

filterInfoForCLSID

public static DSFilterInfo filterInfoForCLSID(java.lang.String CLSID)
                                       throws DSJException

Returns a DSFilterInfo for a filter whose CLSID matches the String argument. This queries for filters internally and will fail if the filter has not been registered with COM. CLSID strings should contain curly braces (example: {1209BB63-E9D1-4f03-AC25-426367DEB524}).

Throws:

DSJException

createFileInfo

public static DSFilterInfo createFileInfo(java.lang.String filePath)

Creates a fake filterInfo for a media file. This is only used with DSStreamBufferGraph.createSource(..) when using an mpeg file as source.

filterInfoForProfile

public static DSFilterInfo filterInfoForProfile(java.io.File prx)

Creates a "non standard" FilterInfo from a Windows Media profile file (.prx) as written by Windows Media Profile Editor. Use this for the VideoCompressor parameter to set WM9 advanced and custom profiles in all dsj nethods that write wmv or asf.

filterInfoForProfile

public static DSFilterInfo filterInfoForProfile(java.lang.String rawPrx)

Creates a "non standard" FilterInfo from a Windows Media profile in raw xml form. Use this for the VideoCompressor parameter to set WM9 advanced and custom profiles in all dsj nethods that write wmv or asf.

filterInfoForSystemProfile

public static DSFilterInfo filterInfoForSystemProfile(int index)
                                               throws DSJException

Creates a "non standard" FilterInfo for a predefined Windows Media 8 system profile for use as a VideoCompressor parameter in all dsj nethods that write wmv or asf.
System profiles are the ones that also show up in the properties dialog of the WM encoders. As of WM9 Microsoft do no longer add profiles to this list (as it would just become too many), so these are all WM8 and potentially not very interesting. To use newer profiles, which is generally recommended, look at the two filterInfoForProfile(String..) methods.
Most system profiles are for both video and audio, so they can not be used with audio or video only files or streams. dsj will fall back to default profiles when an av profile is passed in for a video only graph or equivalent!
The total number of system profiles is 27. This method throws an exception when you pass in an invalid index.
A list of predefined system profiles can be found at http://msdn2.microsoft.com/en-US/library/aa390939.aspx

Throws:

DSJException

filterInfoForCodecState

public static DSFilterInfo filterInfoForCodecState(java.lang.String codecName,
                                                   java.io.File savedState)
                                            throws DSJException

Creates a FilterInfo for the registered filter with the given name and enables reconfiguration of the filter to the saved state. See setPreferredFormat and DSFilter.saveFilterState(..) for information on how to save a filter's state.

Throws:

DSJException

filterInfoForCodecState

public static DSFilterInfo filterInfoForCodecState(java.lang.String filterName,
                                                   java.lang.String hexData)
                                            throws DSJException

Creates a FilterInfo for the filter with name %filterName and enables reconfiguration to the filterstate given in the hexstring. The filter refered to must have been properly registered, with COM during installation or by using regsvr32 manually. Refer to the filter's documentation, when installing new filters.

Throws:

DSJException

filterInfoForDll

public static DSFilterInfo filterInfoForDll(java.lang.String fullDllPath,
                                            java.lang.String CLSID)
                                     throws DSJException

Creates a FilterInfo for an unregistered DirectShow filter "contained" in the given .dll or .ax file. This may be useful if you wish to work with application private filters that for some reason are not to be made available systemwide.
%fullDllPath - absolute path to the dll
%CLSID - the COM object's globally unique identifier.
Note that this will not work for DMOs, ICM & ACM codecs and anything else that uses wrapper filters.

Throws:

DSJException

toString

public java.lang.String toString()

Returns an informative String, containing info about the described filter, its pins and their formats

Overrides:

toString in class java.lang.Object

getPath

public java.lang.String getPath()

getName

public java.lang.String getName()

getCLSID

public java.lang.String getCLSID()

getSubGUID

public java.lang.String getSubGUID()

getDllLocation

public java.lang.String getDllLocation()
                                throws DSJException

Returns the location of the .ax. or .dll file containing the filter implementation.

Throws:

DSJException

getType

public int getType()

Deprecated. method, getType() is deprecated. This was previously used to categorize capture devices. Examine the output formats to do so.

isNullInfo

public boolean isNullInfo()

Returns true for "doNotRender()" DSFilterinfos.

setPreferredFormat

public void setPreferredFormat(int fIndex)

Used to make DirectShow render at a specific format when constructing a filter instance with a DSFilterInfo argument. This is in first hand used with capture devices and encoders.
%fIndex - the index into the formats a filter supports for the filter's output pin. For filters with multiple outputs - as capture devices - set the format directly on the pins.

There are two special "formats" you can use with encoder filters here:
SHOW_USER_DIALOG - will bring up the native settings dialog when the filter is put into the graph.
SHOW_DLG_SAVE - also brings up the settings dialog and saves the configuration into a temporary file. You can use DSEnvironment.persistCodecState(...) to permanently save the settings to a place of your choice. The saved state can then be used with the filterInfoForCodecState(...) method. There is no guarantee that the filter will save any useful information about its current configuration though, as DirectShow does not define any standard, that filters need to follow. Encoders that use the ICM or ACM Wrapper (Image / Audio Compression Manager) will mostly save information, that can be used to restore their settings, while "independent" filters may either serialize their state or store it in the registry (again without following a standard)

getPreferredFormat

public int getPreferredFormat()

compareTo

public int compareTo(java.lang.Object dsfi)

Specified by:

compareTo in interface java.lang.Comparable

getPins

public DSFilterInfo.DSPinInfo[] getPins()

Gets all inputs and outputs

getDownstreamPins

public DSFilterInfo.DSPinInfo[] getDownstreamPins()

Gets a filters outputs

getUpstreamPins

public DSFilterInfo.DSPinInfo[] getUpstreamPins()

Gets a filters inputs

getCrossBarInfo

public DSFilterInfo.DSCrossBarInfo getCrossBarInfo()

Returns the crossbar info on analogue video & TV capture devices or null

getTVTunerInfo

public DSFilterInfo.DSTVTunerInfo getTVTunerInfo()

Returns the TVTuner info on TV devices or null

resolve

public boolean resolve()

DSFilterInfos may have varying informational depth, depending on how they were constructed and whether they belong to a DSFilter in a filtergraph. This method will try to fill in all possible fields, which however may also not give you all possible information in case the DSFilterInfo does not belong to a DSFilter. If it does have a filter backing, the FilterInfo read back from the filter (DSFilter.getFilterInfo()) will usually be fully resolved.