On Saturday 14 October 2006 18:34, Duncan Webb wrote:
> Hi all,
>
> I've got two question, hopefully not too stupid:
> >From the ivtv-0.8.0 ChangeLog
>
> - Replaced IVTV_IOC_S/G_CODEC by the new V4L2 MPEG encoding API.
> - Replaced IVTV_IOC_S/G_VBI_EMBED by the new V4L2 MPEG encoding API.
>
> 1) What are the new VIDIOC controls, for the old IVTV_IOC?
The reference section for these ioctls is already available in the v4l2
spec, but not yet the user-level explanation. I've finished that part
today and just mailed it to the v4l2 spec maintainer, but I've also
attached it to this mail for you to read.
>
> It's not obvious from the documentation or the test programs what
> they are.
>
> 2) What is the difference between set/get-set-vbi and
> set/get-vbi-passthrough?
passthrough is for the PVR350 only: if you choose passthrough mode (e.g.
the tuner input is internally redirected to the TV-out) then you can
use this to also passthrough the VBI data, although that is limited to
CC for NTSC and VPS and WSS for PAL.
To be honest, I've no idea if it still works and how well it works, it's
rarely tested.
Hans
1.9. Extended Controls
1.9.1 Introduction
The control mechanism as originally designed was meant to be used for
user settings (brightness, saturation, etc). However, it turned out to be a
very useful model for implementing more complicated driver APIs where each
driver implements only a subset of a larger API.
The MPEG encoding API was the driving force behind designing and implementing
this extended control mechanism: the MPEG standard is quite large and the
currently supported hardware MPEG encoders each only implement a subset of this
standard. Further more, many parameters relating to how the video is encoded
into
an MPEG stream are specific to the MPEG encoding chip since the MPEG standard
only defines the format of the resulting MPEG stream, not how the video is
actually encoded into that format.
Unfortunately, the original control API lacked some features needed for these
new uses and so it was extended into the (not terribly originally named)
extended
control API.
1.9.2 The Extended Control API
Three new ioctls are available: VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS
and VIDIOC_TRY_EXT_CTRLS. These ioctls act on arrays of controls (as opposed
to the VIDIOC_G_CTRL and VIDIOC_S_CTRL ioctls that act on a single control).
This is needed since it is often required to set several controls simulatenously
(atomically).
Each of the new ioctls expects a pointer to a struct v4l2_ext_controls. This
structure contains a pointer to the control array, a count of the number of
controls in that array and a control class. Control classes are used to
group similar controls into a single class. For example, control class
V4L2_CTRL_CLASS_USER
contains all user controls (i.e. all controls that can also be set using
the old VIDIOC_S_CTRL ioctl). Control class V4L2_CTRL_CLASS_MPEG contains
all controls relating to MPEG encoding, etc.
All controls in the control array must belong to the specified control class.
An error is returned if this is not the case.
It is also possible to use an empty control array (count == 0) to check whether
the specified control class is supported.
The control array is a struct v4l2_ext_control array. The v4l2_ext_control
struct
is very similar to the v4l2_control struct, except for the fact that it also
allows for 64-bit values and pointers to be passed (although the latter is not
yet used anywhere).
It is important to realize that due to the flexibility of controls it is
necessary to check whether the control you want to set actually is supported
in the driver and what the valid range of values is. So use the VIDIOC_QUERYCTRL
and VIDIOC_QUERYMENU ioctls to check this. Also note that it is possible that
some of the menu indices in a control of type V4L2_CTRL_TYPE_MENU may not
be supported (VIDIOC_QUERYMENU will return an error). A good example is the
list of supported MPEG audio bitrates. Some drivers only support one or two
bitrates, others support a wider range.
1.9.3 Enumerating Extended Controls
The recommended way to enumerate over the extended controls is by using
VIDIOC_QUERYCTRL in combination with the V4L2_CTRL_FLAG_NEXT_CTRL flag:
struct v4l2_queryctrl qctrl;
qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
while (ioctl(fd, VIDIOC_QUERYCTRL, &qctrl) == 0) {
// ...
qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
}
The initial control ID is set to 0 ORed with the V4L2_CTRL_FLAG_NEXT_CTRL flag.
The VIDIOC_QUERYCTRL will return the first control with a higher ID than the
specified one. When no such controls are found an error is returned.
If you want to get all controls within a specific control class, then you can
set
the initial qctrl.id value to the control class and add an extra check to
break out of the loop when a control of another control class is found:
qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
while (ioctl(fd, VIDIOC_QUERYCTRL, &qctrl) == 0) {
if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG)
break;
// ...
qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
}
The 32-bit qctrl.id value is subdivided into three bit ranges: the top 4 bits
are reserved for flags (e.g. V4L2_CTRL_FLAG_NEXT_CTRL) and are not actually part
of the ID. The remaining 28 bits form the control ID, of which the most
significant
12 bits define the control class and the least significant 16 bits identify
the control within the control class. It is guaranteed that these last 16 bits
are always non-zero for controls. The range of 0x1000 and up are reserved for
driver-specific controls. The macro V4L2_CTRL_ID2CLASS(id) returns the
control class ID based on a control ID.
If the driver does not support extended controls, then VIDIOC_QUERYCTRL will
fail when used in combination with V4L2_CTRL_FLAG_NEXT_CTRL. In that case the
old
method of enumerating control should be used (see 1.8). But if it is supported,
then
it is guaranteed to enumerate over all controls, including driver-private
controls.
1.9.4 Creating Control Panels
It is possible to create control panels for a graphical user interface where the
user can select the various controls. Basically you will have to iterate over
all
controls using the method described above. Each control class starts with a
control of type V4L2_CTRL_TYPE_CTRL_CLASS. VIDIOC_QUERYCTRL will return the name
of this control class which can be used as the title of a tab page within a
control panel.
The flags field of the v4l2_queryctrl struct also contains hints on the behavior
of the control. See the VIDIOC_QUERYCTRL documentation for more details.
1.9.5 MPEG Control Reference
Below all controls within the MPEG control class are described. First the
generic controls, then controls specific for certain hardware.
1.9.5.1 Generic MPEG Controls
Table 1-1. MPEG Control IDs
ID Type Description
V4L2_CID_MPEG_CLASS class
The MPEG class descriptor. Calling
VIDIOC_QUERYCTRL for this control will return a description of this control
class. This description can be used as the caption of a Tab page in a GUI, for
example.
V4L2_CID_MPEG_STREAM_TYPE enum
The MPEG-1, -2 or -4 output stream type. One
cannot assume anything here. Each hardware MPEG encoder tends to
support different subsets of the available MPEG stream types.
The currently defined stream types are:
V4L2_MPEG_STREAM_TYPE_MPEG2_PS MPEG-2 program stream
V4L2_MPEG_STREAM_TYPE_MPEG2_TS MPEG-2 transport stream
V4L2_MPEG_STREAM_TYPE_MPEG1_SS MPEG-1 system stream
V4L2_MPEG_STREAM_TYPE_MPEG2_DVD MPEG-2 DVD-compatible stream
V4L2_MPEG_STREAM_TYPE_MPEG1_VCD MPEG-1 VCD-compatible stream
V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD MPEG-2 SVCD-compatible stream
V4L2_CID_MPEG_STREAM_PID_PMT integer
Program Map Table Packet ID for the MPEG transport stream (default 16)
V4L2_CID_MPEG_STREAM_PID_AUDIO integer
Audio Packet ID for the MPEG transport stream (default 256)
V4L2_CID_MPEG_STREAM_PID_VIDEO integer
Video Packet ID for the MPEG transport stream (default 260)
V4L2_CID_MPEG_STREAM_PID_PCR integer
Packet ID for the MPEG transport stream carrying PCR fields (default 259)
V4L2_CID_MPEG_STREAM_PES_ID_AUDIO integer
Audio ID for MPEG PES.
V4L2_CID_MPEG_STREAM_PES_ID_VIDEO integer
Video ID for MPEG PES.
V4L2_CID_MPEG_STREAM_VBI_FMT enum
Some cards can embed VBI data (e.g. Closed
Captions, teletext, etc) into the MPEG stream. This control selects whether
VBI data should be embedded, and if so, what embedding method should be used.
The list of possible VBI formats depends on the driver.
The currently defined VBI format types are:
V4L2_MPEG_STREAM_VBI_FMT_NONE No VBI in the MPEG stream
V4L2_MPEG_STREAM_VBI_FMT_IVTV VBI in private packets, IVTV format
(documented in README.vbi)
V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ enum
MPEG Audio sampling frequency. Possible values are:
V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100 44.1 kHz
V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000 48 kHz
V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000 32 kHz
V4L2_CID_MPEG_AUDIO_ENCODING enum
MPEG Audio encoding. Possible values are:
V4L2_MPEG_AUDIO_ENCODING_LAYER_1 MPEG Layer I encoding
V4L2_MPEG_AUDIO_ENCODING_LAYER_2 MPEG Layer II encoding
V4L2_MPEG_AUDIO_ENCODING_LAYER_3 MPEG Layer III encoding
V4L2_CID_MPEG_AUDIO_L1_BITRATE enum
Layer I bitrate. Possible values are:
V4L2_MPEG_AUDIO_L1_BITRATE_32K 32 kbit/s
V4L2_MPEG_AUDIO_L1_BITRATE_64K 64 kbit/s
V4L2_MPEG_AUDIO_L1_BITRATE_96K 96 kbit/s
V4L2_MPEG_AUDIO_L1_BITRATE_128K 128 kbit/s
V4L2_MPEG_AUDIO_L1_BITRATE_160K 160 kbit/s
V4L2_MPEG_AUDIO_L1_BITRATE_192K 192 kbit/s
V4L2_MPEG_AUDIO_L1_BITRATE_224K 224 kbit/s
V4L2_MPEG_AUDIO_L1_BITRATE_256K 256 kbit/s
V4L2_MPEG_AUDIO_L1_BITRATE_288K 288 kbit/s
V4L2_MPEG_AUDIO_L1_BITRATE_320K 320 kbit/s
V4L2_MPEG_AUDIO_L1_BITRATE_352K 352 kbit/s
V4L2_MPEG_AUDIO_L1_BITRATE_384K 384 kbit/s
V4L2_MPEG_AUDIO_L1_BITRATE_416K 416 kbit/s
V4L2_MPEG_AUDIO_L1_BITRATE_448K 448 kbit/s
V4L2_CID_MPEG_AUDIO_L2_BITRATE enum
Layer II bitrate. Possible values are:
V4L2_MPEG_AUDIO_L2_BITRATE_32K 32 kbit/s
V4L2_MPEG_AUDIO_L2_BITRATE_48K 48 kbit/s
V4L2_MPEG_AUDIO_L2_BITRATE_56K 56 kbit/s
V4L2_MPEG_AUDIO_L2_BITRATE_64K 64 kbit/s
V4L2_MPEG_AUDIO_L2_BITRATE_80K 80 kbit/s
V4L2_MPEG_AUDIO_L2_BITRATE_96K 96 kbit/s
V4L2_MPEG_AUDIO_L2_BITRATE_112K 112 kbit/s
V4L2_MPEG_AUDIO_L2_BITRATE_128K 128 kbit/s
V4L2_MPEG_AUDIO_L2_BITRATE_160K 160 kbit/s
V4L2_MPEG_AUDIO_L2_BITRATE_192K 192 kbit/s
V4L2_MPEG_AUDIO_L2_BITRATE_224K 224 kbit/s
V4L2_MPEG_AUDIO_L2_BITRATE_256K 256 kbit/s
V4L2_MPEG_AUDIO_L2_BITRATE_320K 320 kbit/s
V4L2_MPEG_AUDIO_L2_BITRATE_384K 384 kbit/s
V4L2_CID_MPEG_AUDIO_L3_BITRATE enum
Layer III bitrate. Possible values are:
V4L2_MPEG_AUDIO_L3_BITRATE_32K 32 kbit/s
V4L2_MPEG_AUDIO_L3_BITRATE_40K 40 kbit/s
V4L2_MPEG_AUDIO_L3_BITRATE_48K 48 kbit/s
V4L2_MPEG_AUDIO_L3_BITRATE_56K 56 kbit/s
V4L2_MPEG_AUDIO_L3_BITRATE_64K 64 kbit/s
V4L2_MPEG_AUDIO_L3_BITRATE_80K 80 kbit/s
V4L2_MPEG_AUDIO_L3_BITRATE_96K 96 kbit/s
V4L2_MPEG_AUDIO_L3_BITRATE_112K 112 kbit/s
V4L2_MPEG_AUDIO_L3_BITRATE_128K 128 kbit/s
V4L2_MPEG_AUDIO_L3_BITRATE_160K 160 kbit/s
V4L2_MPEG_AUDIO_L3_BITRATE_192K 192 kbit/s
V4L2_MPEG_AUDIO_L3_BITRATE_224K 224 kbit/s
V4L2_MPEG_AUDIO_L3_BITRATE_256K 256 kbit/s
V4L2_MPEG_AUDIO_L3_BITRATE_320K 320 kbit/s
V4L2_CID_MPEG_AUDIO_MODE enum
MPEG Audio mode. Possible values are:
V4L2_MPEG_AUDIO_MODE_STEREO Stereo
V4L2_MPEG_AUDIO_MODE_JOINT_STEREO Joint Stereo
V4L2_MPEG_AUDIO_MODE_DUAL Bilingual
V4L2_MPEG_AUDIO_MODE_MONO Mono
V4L2_CID_MPEG_AUDIO_MODE_EXTENSION enum
Joint Stereo audio mode extension.
In Layer I and II they indicate which subbands are in intensity stereo. All
other subbands are coded in stereo. Layer III is not (yet) supported.
Possible values are:
V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4 subbands 4-31 in intensity
stereo
V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8 subbands 8-31 in intensity
stereo
V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12 subbands 12-31 in intensity
stereo
V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16 subbands 16-31 in intensity
stereo
V4L2_CID_MPEG_AUDIO_EMPHASIS enum
Audio Emphasis. Possible values are:
V4L2_MPEG_AUDIO_EMPHASIS_NONE None
V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS 50/15 microsecond emphasis
V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17 CCITT J.17
V4L2_CID_MPEG_AUDIO_CRC enum
CRC method. Possible values are:
V4L2_MPEG_AUDIO_CRC_NONE None
V4L2_MPEG_AUDIO_CRC_CRC16 16 bit parity check
V4L2_CID_MPEG_VIDEO_ENCODING enum
MPEG Video encoding method. Possible values are:
V4L2_MPEG_VIDEO_ENCODING_MPEG_1 MPEG-1 Video encoding.
V4L2_MPEG_VIDEO_ENCODING_MPEG_2 MPEG-2 Video encoding.
V4L2_CID_MPEG_VIDEO_ASPECT enum
Video aspect. Possible values are:
V4L2_MPEG_VIDEO_ASPECT_1x1
V4L2_MPEG_VIDEO_ASPECT_4x3
V4L2_MPEG_VIDEO_ASPECT_16x9
V4L2_MPEG_VIDEO_ASPECT_221x100
V4L2_CID_MPEG_VIDEO_B_FRAMES integer
Number of B-Frames. (Default 2)
V4L2_CID_MPEG_VIDEO_GOP_SIZE integer
GOP size. (Default 12)
V4L2_CID_MPEG_VIDEO_GOP_CLOSURE bool
GOP closure. (Default 1)
V4L2_CID_MPEG_VIDEO_PULLDOWN bool
Enable 3:2 pulldown (Default 0)
V4L2_CID_MPEG_VIDEO_BITRATE_MODE enum
Video bitrate mode. Possible values are:
V4L2_MPEG_VIDEO_BITRATE_MODE_VBR Variable bitrate
V4L2_MPEG_VIDEO_BITRATE_MODE_CBR Constant bitrate
V4L2_CID_MPEG_VIDEO_BITRATE integer
Video bitrate in bits per second.
V4L2_CID_MPEG_VIDEO_BITRATE_PEAK integer
Peak video bitrate in bits per second.
Must be larger or equal to the average video bitrate. It is ignored if the
video bitrate mode is set to Constant bitrate.
V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION integer
For every captured frame, skip this many subsequent frames. (Default 0).
1.9.5.2 CX2341x MPEG Controls
Table 1-2. CX2341x MPEG Control IDs
ID Type Description
The following MPEG class controls deal
with MPEG encoding settings that are specific to the Conexant CX23415/6 MPEG
encoding
chips.
V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE enum
Sets the Spatial Filter mode (Default: manual). Possible values are:
V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL Choose the filter
manually
V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO Choose the filter
automatically
V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER integer (0-15)
The setting for the Spatial Filter. 0 = off, 15 = maximum. (Default 0)
V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE enum
Select the algorithm to use for the Luma Spatial Filter (Default 1D_HOR).
Possible values:
V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF No filter
V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR One-dimensional
horizontal
V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT
One-dimensional vertical
V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE
Two-dimensional separable
V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE
Two-dimensional symmetrical non-separable
V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE enum
Select the algorithm for the Chroma Spatial Filter (Default 1D_HOR). Possible
values are:
V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF No filter
V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR
One-dimensional horizontal
V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE enum
Sets the Temporal Filter mode (Default: manual). Possible values are:
V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL Choose the filter
manually
V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO Choose the filter
automatically
V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER integer (0-31)
The setting for the Temporal Filter. 0 = off, 31 = maximum. (Default is 8 for
full-scale capturing
and 0 for scaled capturing).
V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE enum
Median Filter Type (Default OFF). Possible values are:
V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF No filter
V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR Horizontal filter
V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT Vertical filter
V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT Horizontal and
Vertical filter
V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG Diagonal filter
V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM integer (0-255)
Threshold above which the luminance median filter is enabled. (Default 0)
V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP integer (0-255)
Threshold below which the luminance median filter is enabled (Default 255)
V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM integer (0-255)
Threshold above which the chroma median filter is enabled (Default 0)
V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP integer (0-255)
Threshold below which the chroma median filter is enabled (Default 255)
_______________________________________________
ivtv-devel mailing list
[email protected]
http://ivtvdriver.org/mailman/listinfo/ivtv-devel
