VBIFilterGroup

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.ocap.media
Class VBIFilterGroup

    java.lang.Object
      org.ocap.media.VBIFilterGroup

All Implemented Interfaces:
  ResourceProxy, ResourceServer

    public class VBIFilterGroup

extends Object
implements ResourceProxy, ResourceServer

This class represents a group of VBI data filters. The VBI filters in a group are attached to a ServiceContext. Current video played back on the ServiceContext is the target of filtering. If the current video is analog, the filters retrieve specific data in a specified VBI line of the video. The data format is defined in each VBI data specification. If the current video is MPEG video, the filters retrieve specific data in the user_data found in the MPEG picture headers of the video. Data format in user_data is defined in ANSI/SCTE 20 and ANSI/SCTE 21.

When a new VBIFilterGroup is constructed, an application specifies the total number of VBIFilters held by it. The application can create a specified number of new VBIFilter instances via a `newVBIFilter(int[], int, int, int, int)` method. VBI lines and data format for filtering are specified in this method. After configuring all filters, the VBIFilterGroup is attached to a specific ServiceContext. Current video on the ServiceContext is the target of filtering. If the startFiltering() method of a VBI filter is called, the filter starts filtering immediately. The application can retrieve VBI data via a `VBIFilter.getVBIData()` method. The host may be able to filter VBI data by using separated fields (specify either field 1 or field 2 and retrieve data in only the specified field) or by using mixed fields (retrieve data in both field 1 and 2 in arrival order).

The data unit is defined as follows.

XDS (VBI_DATA_FORMAT_XDS)
XDS packets in line 21 field 2 is defined in EIA-608-B. It has a start/continue/end code and is interleaved with CC3, CC4, T3 and T4 service. One XDS packet is a single data unit of this data format.

Text service (VBI_DATA_FORMAT_T1/T2/T3/T4)
Text service data in line 21 field 1 or 2 is defined in EIA-608-B. It has start/end codes and is interleaved with the other closed captioning service and Text service according to Section 7 of EIA-608-B. A single data unit of Text service is a character sequence between a text mode in code (RTD or TR) and a text mode out code (EOC, RCL, RDC, RU2, RU3 or RU4). Note that Text service data unit returned from the VBIFilter doesn't contain these text mode in/out codes, but contains another control codes like EDM etc.

Generic EIA-608-B service (VBI_DATA_FORMAT_EIA608B)
Generic EIA-608-B service represents a character stream that consists of Character One and Character Two in a field of line 21. Character One and Character Two are defined in Figure 1 of EIA-608-B. Note that the VBIFilter only supports separated field filtering since Character One and Character Two make a separate data stream in each field. A single data unit of this format is a set of Character One and Character Two in one VBI line and field (i.e., only two characters).

NABTS (VBI_DATA_FORMAT_NABTS)
NABTS is defined in EIA-516. It is a 33 byte fixed length packet and consists of 5 byte prefix and 28 byte data block. Note that the filter retrieves only the "Data packet" part. I.e., one NABTS packet is a single data unit. The VBIFilter retrieves multiple NABTS packets in arrival order for all specified lines and fields.

AMOL I/II (VBI_DATA_FORMAT_AMOL_I/II)
AMOL I and II is defined in ACN 403-1218-024. It specifies header bits and the number of bits in a VBI line . The bits in one VBI line/field is a single data unit for this data format, i.e., the header bits are included in the data unit.

UNKNOWN (VBI_DATA_FORMAT_UNKNOWN)
UNKNOWN represents a VBI waveform that is unknown. To retrieve UNKNOWN data unit, the OCAP implementation needs to synchronize to the VBI's bit rate automatically. Filtering success is not guaranteed even if the OCAP implementation supports the UNKNOWN format, since an analog waveform is not standardized. The bits in one VBI line and field is a data unit for UNKNOWN format.

OCAP 1.0 hosts SHALL support retrieval of T1 and T2 data in VBI line 21 field 1 and T3, T4 and XDS in VBI line 21 field 2 via this API. Note that filtering of closed caption services (CC1-CC4) is not provided by this API (the `ClosedCaptioningControl` interface is used to control closed captioning display). In general, this API is not intended for synchronized on-screen display of filtered data with video and audio, as filter performance is not guaranteed to be within an acceptable delay.

Support of the other VBI lines is optional. And support of the ANSI/SCTE 20 and ANSI/SCTE 21 is also optional. An application can check the supported filtering lines, data format and filtering techniques (field separated or field mixed) via capability methods.

Author:
  Shigeaki Watanabe (Panasonic)

Field Summary
`static int` | `FIELD_1` Represents filtering of VBI data in field 1 only.
`static int` | `FIELD_2` Represents filtering of VBI data in field 2 only.
`static int` | `FIELD_MIXED` Represents filtering of VBI data in both field 1 and field 2 in arrival order.
`static int` | `VBI_DATA_FORMAT_AMOL_I` Represents an AMOL I data format defined by ACN 403-1218-024.
`static int` | `VBI_DATA_FORMAT_AMOL_II` Represents an AMOL II data format defined by ACN 403-1218-024.
`static int` | `VBI_DATA_FORMAT_EIA608B` Represents a EIA-608-B generic Character One and Character Two format of line 21 field 1 or 2.
`static int` | `VBI_DATA_FORMAT_NABTS` Represents an NABTS data format defined by EIA-516.
`static int` | `VBI_DATA_FORMAT_T1` Represents a Text service T1 format of line 21 field 1.
`static int` | `VBI_DATA_FORMAT_T2` Represents a Text service T2 format of line 21 field 1.
`static int` | `VBI_DATA_FORMAT_T3` Represents a Text service T3 format of line 21 field 2.
`static int` | `VBI_DATA_FORMAT_T4` Represents a Text service T4 format of line 21 field 2.
`static int` | `VBI_DATA_FORMAT_UNKNOWN` Represents an unknown.
`static int` | `VBI_DATA_FORMAT_XDS` Represents a XDS data format of line 21 field 2.

Constructor Summary
`VBIFilterGroup(int numberOfFilters)` Creates a VBIFilterGroup instance that includes the specified number of VBI filters.

Method Summary
`void` | `addResourceStatusEventListener(ResourceStatusListener listener)` Add a listener object to be notified of changes in the status of resources related to VBI filters.
`void` | `attach(ServiceContext serviceContext, ResourceClient client, Object requestData)` This method attempts to reserve all VBI filters held by this VBIFilterGroup, and attaches to a specified ServiceContext.
`void` | `detach()` Releases all filters in this VBIFilterGroup and terminates the connection to the ServiceContext.
`ResourceClient` | `getClient()` Returns the ResourceClient object specified in the attach() method.
`boolean` | `getMixedFilteringCapability(int[] lineNumbers, int dataFormat)` Returns true if field mixed filtering of the specified VBI line numbers with the specified data format is supported by this VBIFilterGroup.
`boolean` | `getSCTE20Capability()` Indicates if the host supports line 21 VBI data retrieval from user_data in MPEG picture headers as defined in ANSI/SCTE 20.
`boolean` | `getSCTE21Capability()` Indicates if the host supports line 21 VBI data retrieval from user_data in MPEG picture headers as defined in ANSI/SCTE 21.
`boolean` | `getSeparatedFilteringCapability(int[] lineNumbers, int dataFormat)` Returns true if field separated filtering of the specified VBI line numbers with the specified data format is supported by this VBIFilterGroup.
`ServiceContext` | `getServiceContext()` Returns a ServiceContext instance specified by a `attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object)` method.
`VBIFilter` | `newVBIFilter(int[] lineNumber, int field, int dataFormat, int unitLength, int bufferSize)` Create a new VBIFilter instance within a VBIFilterGroup instance.
`void` | `removeResourceStatusEventListener(ResourceStatusListener listener)` Remove a specified listener object from this VBIFilterGroup.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### VBI_DATA_FORMAT_XDS

    public static final int VBI_DATA_FORMAT_XDS

  Represents a XDS data format of line 21 field 2.

  See Also:
    Constant Field Values

### VBI_DATA_FORMAT_T1

    public static final int VBI_DATA_FORMAT_T1

  Represents a Text service T1 format of line 21 field 1.

  See Also:
    Constant Field Values

### VBI_DATA_FORMAT_T2

    public static final int VBI_DATA_FORMAT_T2

  Represents a Text service T2 format of line 21 field 1.

  See Also:
    Constant Field Values

### VBI_DATA_FORMAT_T3

    public static final int VBI_DATA_FORMAT_T3

  Represents a Text service T3 format of line 21 field 2.

  See Also:
    Constant Field Values

### VBI_DATA_FORMAT_T4

    public static final int VBI_DATA_FORMAT_T4

  Represents a Text service T4 format of line 21 field 2.

  See Also:
    Constant Field Values

### VBI_DATA_FORMAT_EIA608B

    public static final int VBI_DATA_FORMAT_EIA608B

  Represents a EIA-608-B generic Character One and Character Two format of line 21 field 1 or 2.

  See Also:
    Constant Field Values

### VBI_DATA_FORMAT_NABTS

    public static final int VBI_DATA_FORMAT_NABTS

  Represents an NABTS data format defined by EIA-516.

  See Also:
    Constant Field Values

### VBI_DATA_FORMAT_AMOL_I

    public static final int VBI_DATA_FORMAT_AMOL_I

  Represents an AMOL I data format defined by ACN 403-1218-024.

  See Also:
    Constant Field Values

### VBI_DATA_FORMAT_AMOL_II

    public static final int VBI_DATA_FORMAT_AMOL_II

  Represents an AMOL II data format defined by ACN 403-1218-024.

  See Also:
    Constant Field Values

### VBI_DATA_FORMAT_UNKNOWN

    public static final int VBI_DATA_FORMAT_UNKNOWN

  Represents an unknown. I.e., all data bits in the VBI line are retrieved.

  See Also:
    Constant Field Values

### FIELD_1

    public static final int FIELD_1

  Represents filtering of VBI data in field 1 only.

  See Also:
    Constant Field Values

### FIELD_2

    public static final int FIELD_2

  Represents filtering of VBI data in field 2 only.

  See Also:
    Constant Field Values

### FIELD_MIXED

    public static final int FIELD_MIXED

  Represents filtering of VBI data in both field 1 and field 2 in arrival order.

  See Also:
    Constant Field Values

Constructor Detail

### VBIFilterGroup

    public VBIFilterGroup(int numberOfFilters)

  Creates a VBIFilterGroup instance that includes the specified number of VBI filters. The VBI filters are reserved when the `attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object)` method is called.

  Parameters:
    `numberOfFilters` - the number of requested VBI filters held by a new VBIFilterGroup instance.
  Throws:
    `SecurityException` - if the caller doesn't have MonitorAppPermission("vbifiltering").

Method Detail

### newVBIFilter

    public VBIFilter newVBIFilter(int[] lineNumber,
                                  int field,
                                  int dataFormat,
                                  int unitLength,
                                  int bufferSize)

  Create a new VBIFilter instance within a VBIFilterGroup instance. The VBIFilter filters the specified VBI line/field and retrieves data units of the specified format. The filter has an internal buffer of the specified size to store the filtered data units. If the filtered data size exceeds the buffer size, the oversized part of data will be lost.

  Parameters:
    `lineNumber` - an array of VBI line numbers that will be filtered by a returned VBIFilter. If line 21 is specified, the filter also filters user_data defined in ANSI/SCTE 20 and ANSI/SCTE 21, when current video is MPEG. Note that filtering of user_data is optional.
    `field` - a field number that will be filtered by a returned VBIFilter. Only constants defined in this class with the "FIELD_" prefix are valid values.
    If FIELD_MIXED is specified, the VBIFilter filters both field 1 and 2 of the specified lineNumber lines. Filtered data is concatenated in arrival order.
    If FIELD_1 is specified, the VBIFilter filters only field 1 of the specified lineNumber lines.
    If FIELD_2 is specified, the VBIFilter filters only field 2 of the specified lineNumber lines.
    `dataFormat` - specifies the data format to be filtered. Only constants defined in this class with the "VBI_DATA_FORMAT_" prefix are valid values.
    `unitLength` - specify the number of bits (not bytes) of a single data unit for the VBI_DATA_FORMAT_UNKNOWN format. This value shall be ignored for the other well known formats.
    `bufferSize` - number of bytes to specify size of an internal buffer used to hold a VBI data unit.
  Returns:
    a new VBIFilter instance. Total number of filters created by a VBIFilterGroup shall not exceed the number of filters specified by a constructor.
  Throws:
    `IllegalStateException` - if the total number of filters created by this VBIFilterGroup exceeds the number specified by the constructor.
    `IllegalArgumentException` - if this VBIFilterGroup can't create a VBIFilter for specified parameters due to hardware or software restrictions, or the lineNumber is not a capable line, or if the field is not defined in constants, or the specified dataFormat is not defined in constants, or if the bufferSize is 0. For example, if this method is called with lineNumber=21, field=FIELD_1 and dataFormat=VBI_DATA_FORMAT_XDS, this exception is thrown.

### attach

    public void attach(ServiceContext serviceContext,
                       ResourceClient client,
                       Object requestData)
                throws FilterResourceException

  This method attempts to reserve all VBI filters held by this VBIFilterGroup, and attaches to a specified ServiceContext. After the method call, filters can start filtering of VBI data units contained in current selected video on the ServiceContext responding to a `VBIFilter.startFiltering(java.lang.Object)` call. Filters whose startFiltering method was called prior to this method being called shall start filtering immediately. Note that the number of filters specified by a constructor shall be created by the newVBIFilter() method before calling this method. (I.e., VBI lines and a data format shall be specified before resource reservation.)

  Parameters:
    `serviceContext` - a ServiceContext that selects the video to be filtered. It is not necessary that a specified ServiceContext is in the presenting state when this method is called.
    `client` - DAVIC ResourceClient to be used for resource management.
    `requestData` - application specific data to be used for resource management. Null is possible.
  Throws:
    `IllegalArgumentException` - if the serviceContext or the client is null. Note that requestData may be null.
    `IllegalStateException` - if this method is called before creating all filters in this VBIFilterGroup.
    `FilterResourceException` - if reserving the specified filters fails.

### detach

    public void detach()

  Releases all filters in this VBIFilterGroup and terminates the connection to the ServiceContext. All filtering by filters in this group terminates immediately.

  Throws:
    `IllegalStateException` - if this method is called when the filters have already been released and this method does nothing.

### getServiceContext

    public ServiceContext getServiceContext()

  Returns a ServiceContext instance specified by a `attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object)` method.

  Returns:
    the ServiceContext instance specified by the `attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object)` method. Null if no ServiceContext is attached at the moment.

### getSeparatedFilteringCapability

    public boolean getSeparatedFilteringCapability(int[] lineNumbers,
                                                   int dataFormat)

  Returns true if field separated filtering of the specified VBI line numbers with the specified data format is supported by this VBIFilterGroup. For each of the data formats required by OCAP (see the class description above), either this method or the `getMixedFilteringCapability(int[], int)` method shall return true for line 21.

  Parameters:
    `lineNumbers` - an array of line numbers used to determine filtering capability.
    `dataFormat` - a data format used to determine filtering capability.
  Returns:
    true if the host supports field separated filtering of the specified line numbers with the specified data format (i.e., the newVBIFilter() method accepts FIELD_1 or FIELD_2). Otherwise returns false.

### getMixedFilteringCapability

    public boolean getMixedFilteringCapability(int[] lineNumbers,
                                               int dataFormat)

  Returns true if field mixed filtering of the specified VBI line numbers with the specified data format is supported by this VBIFilterGroup. For each of the data formats required by OCAP (see the class description above), either this method or the `getSeparatedFilteringCapability(int[], int)` method shall return true for line 21.

  Parameters:
    `lineNumbers` - an array of line numbers used to determine filtering capability.
    `dataFormat` - a data format used to determine filtering capability.
  Returns:
    true if the host supports field mixed filtering of the specified line numbers with the specified data format (i.e., the newVBIFilter() method accepts FIELD_MIXED). Otherwise returns false.

### getSCTE20Capability

    public boolean getSCTE20Capability()

  Indicates if the host supports line 21 VBI data retrieval from user_data in MPEG picture headers as defined in ANSI/SCTE 20.

  Returns:
    true if the host can retrieve line 21 data from user_data in MPEG picture headers as defined in ANSI/SCTE 20.
  See Also:
    `newVBIFilter(int[], int, int, int, int)`

### getSCTE21Capability

    public boolean getSCTE21Capability()

  Indicates if the host supports line 21 VBI data retrieval from user_data in MPEG picture headers as defined in ANSI/SCTE 21.

  Returns:
    true if the host can retrieve line 21 data from user_data in MPEG picture headers as defined in ANSI/SCTE 21.
  See Also:
    `newVBIFilter(int[], int, int, int, int)`

### getClient

    public ResourceClient getClient()

  Returns the ResourceClient object specified in the attach() method.

  Specified by:
    `getClient` in interface `ResourceProxy`
  Returns:
    the ResourceClient object specified in the last call of the `attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object)` method. If the attach() method has never been called or the `detach()` method is called to cancel an attach call, this method returns null.

### addResourceStatusEventListener

    public void addResourceStatusEventListener(ResourceStatusListener listener)

  Add a listener object to be notified of changes in the status of resources related to VBI filters.

  Specified by:
    `addResourceStatusEventListener` in interface `ResourceServer`
  Parameters:
    `listener` - an object implementing the ResourceStatusListener interface. Multiple calls with the same listener instance are simply ignored without throwing an exception.
  Throws:
    `IllegalArgumentException` - if the listener is null.

### removeResourceStatusEventListener

    public void removeResourceStatusEventListener(ResourceStatusListener listener)

  Remove a specified listener object from this VBIFilterGroup.

  Specified by:
    `removeResourceStatusEventListener` in interface `ResourceServer`
  Parameters:
    `listener` - an object implementing the ResourceStatusListener interface. This method does nothing if the specified listener is null, not previously added or already removed.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD