|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.ocap.media.VBIFilterGroup
public class VBIFilterGroup
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.
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 |
---|
public static final int VBI_DATA_FORMAT_XDS
public static final int VBI_DATA_FORMAT_T1
public static final int VBI_DATA_FORMAT_T2
public static final int VBI_DATA_FORMAT_T3
public static final int VBI_DATA_FORMAT_T4
public static final int VBI_DATA_FORMAT_EIA608B
public static final int VBI_DATA_FORMAT_NABTS
public static final int VBI_DATA_FORMAT_AMOL_I
public static final int VBI_DATA_FORMAT_AMOL_II
public static final int VBI_DATA_FORMAT_UNKNOWN
public static final int FIELD_1
public static final int FIELD_2
public static final int FIELD_MIXED
Constructor Detail |
---|
public VBIFilterGroup(int numberOfFilters)
attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object)
method is called.
numberOfFilters
- the number of requested VBI filters held by
a new VBIFilterGroup instance.
SecurityException
- if the caller doesn't have
MonitorAppPermission("vbifiltering").Method Detail |
---|
public VBIFilter newVBIFilter(int[] lineNumber, int field, int dataFormat, int unitLength, int bufferSize)
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.
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.
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.public void attach(ServiceContext serviceContext, ResourceClient client, Object requestData) throws FilterResourceException
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.)
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.
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.public void detach()
IllegalStateException
- if this method is called when the
filters have already been released and this method does
nothing.public ServiceContext getServiceContext()
attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object)
method.
attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object)
method.
Null if no ServiceContext is attached at the moment.public boolean getSeparatedFilteringCapability(int[] lineNumbers, int dataFormat)
getMixedFilteringCapability(int[], int)
method shall return
true for line 21.
lineNumbers
- an array of line numbers used to determine
filtering capability.dataFormat
- a data format used to determine filtering
capability.
public boolean getMixedFilteringCapability(int[] lineNumbers, int dataFormat)
getSeparatedFilteringCapability(int[], int)
method shall
return true for line 21.
lineNumbers
- an array of line numbers used to determine
filtering capability.dataFormat
- a data format used to determine filtering
capability.
public boolean getSCTE20Capability()
newVBIFilter(int[], int, int, int, int)
public boolean getSCTE21Capability()
newVBIFilter(int[], int, int, int, int)
public ResourceClient getClient()
getClient
in interface ResourceProxy
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.public void addResourceStatusEventListener(ResourceStatusListener listener)
addResourceStatusEventListener
in interface ResourceServer
listener
- an object implementing the ResourceStatusListener
interface.
Multiple calls with the same listener instance are simply
ignored without throwing an exception.
IllegalArgumentException
- if the listener is null.public void removeResourceStatusEventListener(ResourceStatusListener listener)
removeResourceStatusEventListener
in interface ResourceServer
listener
- an object implementing the ResourceStatusListener
interface.
This method does nothing if the specified listener is
null, not previously added or already removed.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |