From 8d4f9d241cdbd71a882a852c6e9285de279c0f87 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sun, 18 Jan 2009 13:00:12 +0100 Subject: v4l2spec: add version 0.24 of the spec From: Hans Verkuil Priority: normal Signed-off-by: Hans Verkuil --- v4l2-spec/vidioc-g-fmt.sgml | 201 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 v4l2-spec/vidioc-g-fmt.sgml (limited to 'v4l2-spec/vidioc-g-fmt.sgml') diff --git a/v4l2-spec/vidioc-g-fmt.sgml b/v4l2-spec/vidioc-g-fmt.sgml new file mode 100644 index 000000000..0a466b2c7 --- /dev/null +++ b/v4l2-spec/vidioc-g-fmt.sgml @@ -0,0 +1,201 @@ + + + ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, +VIDIOC_TRY_FMT + &manvol; + + + + VIDIOC_G_FMT + VIDIOC_S_FMT + VIDIOC_TRY_FMT + Get or set the data format, try a format + + + + + + int ioctl + int fd + int request + struct v4l2_format +*argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT + + + + argp + + + + + + + + + Description + + These ioctls are used to negotiate the format of data +(typically image format) exchanged between driver and +application. + + To query the current parameters applications set the +type field of a struct +v4l2_format to the respective buffer (stream) +type. For example video capture devices use +V4L2_BUF_TYPE_VIDEO_CAPTURE. When the application +calls the VIDIOC_G_FMT ioctl with a pointer to +this structure the driver fills the respective member of the +fmt union. In case of video capture devices +that is the &v4l2-pix-format; pix member. +When the requested buffer type is not supported drivers return an +&EINVAL;. + + To change the current format parameters applications +initialize the type field and all +fields of the respective fmt +union member. For details see the documentation of the various devices +types in . Good practice is to query the +current parameters first, and to +modify only those parameters not suitable for the application. When +the application calls the VIDIOC_S_FMT ioctl +with a pointer to a v4l2_format structure +the driver checks +and adjusts the parameters against hardware abilities. Drivers +should not return an error code unless the input is ambiguous, this is +a mechanism to fathom device capabilities and to approach parameters +acceptable for both the application and driver. On success the driver +may program the hardware, allocate resources and generally prepare for +data exchange. +Finally the VIDIOC_S_FMT ioctl returns the +current format parameters as VIDIOC_G_FMT does. +Very simple, inflexible devices may even ignore all input and always +return the default parameters. However all V4L2 devices exchanging +data with the application must implement the +VIDIOC_G_FMT and +VIDIOC_S_FMT ioctl. When the requested buffer +type is not supported drivers return an &EINVAL; on a +VIDIOC_S_FMT attempt. When I/O is already in +progress or the resource is not available for other reasons drivers +return the &EBUSY;. + + The VIDIOC_TRY_FMT ioctl is equivalent +to VIDIOC_S_FMT with one exception: it does not +change driver state. It can also be called at any time, never +returning EBUSY. This function is provided to +negotiate parameters, to learn about hardware limitations, without +disabling I/O or possibly time consuming hardware preparations. +Although strongly recommended drivers are not required to implement +this ioctl. + + + struct <structname>v4l2_format</structname> + + + + + + + + &v4l2-buf-type; + type + + Type of the data stream, see . + + + union + fmt + + + + &v4l2-pix-format; + pix + Definition of an image format, see , used by video capture and output +devices. + + + + &v4l2-window; + win + Definition of an overlaid image, see , used by video overlay devices. + + + + &v4l2-vbi-format; + vbi + Raw VBI capture or output parameters. This is +discussed in more detail in . Used by raw VBI +capture and output devices. + + + + &v4l2-sliced-vbi-format; + sliced + Sliced VBI capture or output parameters. See + for details. Used by sliced VBI +capture and output devices. + + + + __u8 + raw_data[200] + Place holder for future extensions and custom +(driver defined) formats with type +V4L2_BUF_TYPE_PRIVATE and higher. + + + +
+ + + + &return-value; + + + + EBUSY + + The data format cannot be changed at this +time, for example because I/O is already in progress. + + + + EINVAL + + The &v4l2-format; type +field is invalid, the requested buffer type not supported, or +VIDIOC_TRY_FMT was called and is not +supported with this buffer type. + + + + + + + -- cgit v1.2.3