This documents the new VIDIOC_G_ENC_INDEX, VIDIOC_ENCODER_CMD and
VIDIOC_TRY_ENCODER_CMD ioctls that appear in kernel 2.6.21.
I've CC-ed this as well to the ivtv-devel mailinglist, since currently
only ivtv implements these ioctls.
Regards,
Hans
ioctl VIDIOC_G_ENC_INDEX
Name
VIDIOC_G_ENC_INDEX -- Get the index of the encoded stream
Status
Experimental
Synopsis
int ioctl(int fd, int request, struct v4l2_enc_idx *argp);
Arguments
fd File descriptor returned by open().
request VIDIOC_G_ENC_INDEX
argp
Description
Return MPEG stream indices. I.e. at the given offset a frame starts (P/I/B
according to the flags) and with the given PTS (Presentation Time Stamp)
and length. The offset may never exceed the number of bytes actually read.
I.e. it should never return 'future events'.
This information is very useful when implementing random access into an MPEG
stream, since it makes it easy to jump directly to the start of an I frame
(which is usually what you want) without having to parse the MPEG stream
manually.
'entries' is the number of entries filled in the entry array. This may be 0
if there are no entries available.
'entries_cap' is the capacity of the index in the driver. This may be
larger or smalled than V4L2_ENC_IDX_ENTRIES. 'entries' will always be less
or equal to min(entries_cap, V4L2_ENC_IDX_ENTRIES).
If this ioctl is called when no capture is in progress, then 'entries' is
0 and 'entries_cap' should be set to the capacity. This way applications
can check beforehand how frequently the index should be obtained.
Table 1. struct v4l2_enc_idx_entry
__u64 offset The offset in bytes in the captured file. Note that the
offset is reset to 0 if the encoder is stopped.
__u64 pts The 33-bit Presentation Time Stamp as
defined in ITU T-REC-H.222.0 / ISO/IEC 13818-1.
__u32 length The length of the frame in bytes.
__u32 flags Flags determining the type of frame (see table 2).
__u32 reserved[2] Must be set to 0 by the driver.
Table 2. Index Entry Types
Symbol Value Description
V4L2_ENC_IDX_FRAME_I 0 This is an I-frame
V4L2_ENC_IDX_FRAME_P 1 This is a P-frame
V4L2_ENC_IDX_FRAME_B 2 This is a B-frame
V4L2_ENC_IDX_FRAME_MASK 0xf 'AND' the flags field with this mask to
obtain the frame type.
Table 3. struct v4l2_enc_idx
__u32 entries The number of entries filled in the entry array
__u32 entries_cap The maximum number of entries the driver can queue
before the oldest entries are overwritten.
__u32 reserved[4] Must be set to 0 by the driver.
struct v4l2_enc_idx_entry entry[V4L2_ENC_IDX_ENTRIES] The recorded entries.
Return Value
On success 0 is returned, on error -1 and the errno variable is set
appropriately:
EINVAL
The driver does not support this ioctl.
ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
Name
VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD -- Execute an encoder command
Status
Experimental
Synopsis
int ioctl(int fd, int request, struct v4l2_encoder_cmd *argp);
int ioctl(int fd, int request, struct v4l2_encoder_cmd *argp);
Arguments
fd File descriptor returned by open().
request VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
argp
Description
These commands are used to command a compressed-stream encoder (which is
generally an MPEG encoder).
Before calling these ioctls the unused fields of v4l2_encoder_cmd must
be zeroed.
'cmd' is set by the user and is the command for the encoder.
'flags' is currently only used by the STOP command and contains one bit:
If V4L2_ENC_CMD_STOP_AT_GOP_END is set, then the capture continues until the
end of the GOP, otherwise it stops immediately.
These ioctls will check whether the command is supported (-EINVAL is
returned if not) and modify any arguments if needed to make it a
valid call for the available hardware. The modified arguments are
returned. The VIDIOC_TRY_ENCODER_CMD is identical to VIDIOC_ENCODER_CMD,
except that the TRY ioctl does not actually execute the command.
Note that a read() to a stopped encoder implies a V4L2_ENC_CMD_START. A
close() of an encoder that is currently encoding implies an immediate
V4L2_ENC_CMD_STOP. When the encoder has no more pending data after issuing
a STOP the read() call will return 0 to indicate that the encoder has stopped.
The next read will start the encoder again.
Table 1. struct v4l2_encoder_cmd
__u32 cmd The encoder command. See table 2 for a list of available
commands.
__u32 flags Flags to accompany the command. See table 2 which flags are
available
with each command. If there are no flags available, then zero
this field.
__u32 data[8] A union field which reserves space for future extensions. Must
be set to 0.
Table 2. Encoder commands
Symbol Value Description
V4L2_ENC_CMD_START 0 Start the encoder. If the encoder is already running
then
this command does nothing. This implies that if the
encoder
is paused, it will remain paused.
There are no flags with this command.
V4L2_ENC_CMD_STOP 1 Stop the encoder. By default the encoder will stop
immediately,
but if the V4L2_ENC_CMD_STOP_AT_GOP_END flag is set,
then the
encoder will continue until the end of the current GOP
(Group-of-Pictures).
If the encoder is already stopped, then this command
does nothing.
V4L2_ENC_CMD_PAUSE 2 Pause the encoder. If the encoder is not started,
then the error
EPERM is returned. If the encoder is already paused,
then this
command does nothing.
There are no flags with this command.
V4L2_ENC_CMD_RESUME 3 Resume the encoder. If the encoder is not started,
then the error
EPERM is returned. If the encoder is not paused, then
this
command does nothing. There are no flags with this
command.
Return Value
On success 0 is returned, on error -1 and the errno variable is set
appropriately:
EINVAL
The driver does not support this ioctl.
EPERM
An attempt is made to pause or resume the encoder when the encoder is not
running.
_______________________________________________
ivtv-devel mailing list
ivtv-devel@ivtvdriver.org
http://ivtvdriver.org/mailman/listinfo/ivtv-devel
