From 4266129964b8238526936d723de65b419d8069c6 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 31 May 2011 16:27:44 -0300 Subject: [media] DocBook: Move all media docbook stuff into its own directory This patch addresses several issues pointed by Randy Dunlap at changeset ece722c: - In the generated index.html file, "media" is listed first, but it should be listed in alphabetical order, not first. - The generated files are (hidden) in .tmpmedia/ - The link from the top-level index.html file to "media" is to media/index.html, but the file is actually in .tmpmedia/media/index.html - Please build docs with and without using "O=builddir" and test that. - Would it be possible for media to have its own Makefile instead of merging into this one? Due to the way cleandocs target works, I had to rename the media DocBook to media_api, otherwise cleandocs would remove the /media directory. Thanks-to: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/v4l/vidioc-g-fbuf.xml | 473 ---------------------------- 1 file changed, 473 deletions(-) delete mode 100644 Documentation/DocBook/v4l/vidioc-g-fbuf.xml (limited to 'Documentation/DocBook/v4l/vidioc-g-fbuf.xml') diff --git a/Documentation/DocBook/v4l/vidioc-g-fbuf.xml b/Documentation/DocBook/v4l/vidioc-g-fbuf.xml deleted file mode 100644 index e7dda4822f04..000000000000 --- a/Documentation/DocBook/v4l/vidioc-g-fbuf.xml +++ /dev/null @@ -1,473 +0,0 @@ - - - ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF - &manvol; - - - - VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters - - - - - - int ioctl - int fd - int request - struct v4l2_framebuffer *argp - - - - - int ioctl - int fd - int request - const struct v4l2_framebuffer *argp - - - - - - Arguments - - - - fd - - &fd; - - - - request - - VIDIOC_G_FBUF, VIDIOC_S_FBUF - - - - argp - - - - - - - - - Description - - Applications can use the VIDIOC_G_FBUF and -VIDIOC_S_FBUF ioctl to get and set the -framebuffer parameters for a Video -Overlay or Video Output Overlay -(OSD). The type of overlay is implied by the device type (capture or -output device) and can be determined with the &VIDIOC-QUERYCAP; ioctl. -One /dev/videoN device must not support both -kinds of overlay. - - The V4L2 API distinguishes destructive and non-destructive -overlays. A destructive overlay copies captured video images into the -video memory of a graphics card. A non-destructive overlay blends -video images into a VGA signal or graphics into a video signal. -Video Output Overlays are always -non-destructive. - - To get the current parameters applications call the -VIDIOC_G_FBUF ioctl with a pointer to a -v4l2_framebuffer structure. The driver fills -all fields of the structure or returns an &EINVAL; when overlays are -not supported. - - To set the parameters for a Video Output -Overlay, applications must initialize the -flags field of a struct -v4l2_framebuffer. Since the framebuffer is -implemented on the TV card all other parameters are determined by the -driver. When an application calls VIDIOC_S_FBUF -with a pointer to this structure, the driver prepares for the overlay -and returns the framebuffer parameters as -VIDIOC_G_FBUF does, or it returns an error -code. - - To set the parameters for a non-destructive -Video Overlay, applications must initialize the -flags field, the -fmt substructure, and call -VIDIOC_S_FBUF. Again the driver prepares for the -overlay and returns the framebuffer parameters as -VIDIOC_G_FBUF does, or it returns an error -code. - - For a destructive Video Overlay -applications must additionally provide a -base address. Setting up a DMA to a -random memory location can jeopardize the system security, its -stability or even damage the hardware, therefore only the superuser -can set the parameters for a destructive video overlay. - - - - - struct <structname>v4l2_framebuffer</structname> - - &cs-ustr; - - - __u32 - capability - - Overlay capability flags set by the driver, see -. - - - __u32 - flags - - Overlay control flags set by application and -driver, see - - - void * - base - - Physical base address of the framebuffer, -that is the address of the pixel in the top left corner of the -framebuffer.A physical base address may not suit all -platforms. GK notes in theory we should pass something like PCI device -+ memory region + offset instead. If you encounter problems please -discuss on the linux-media mailing list: &v4l-ml;. - - - - - - This field is irrelevant to -non-destructive Video Overlays. For -destructive Video Overlays applications must -provide a base address. The driver may accept only base addresses -which are a multiple of two, four or eight bytes. For -Video Output Overlays the driver must return -a valid base address, so applications can find the corresponding Linux -framebuffer device (see ). - - - &v4l2-pix-format; - fmt - - Layout of the frame buffer. The -v4l2_pix_format structure is defined in , for clarification the fields and acceptable values - are listed below: - - - - __u32 - width - Width of the frame buffer in pixels. - - - - __u32 - height - Height of the frame buffer in pixels. - - - - __u32 - pixelformat - The pixel format of the -framebuffer. - - - - - - For non-destructive Video -Overlays this field only defines a format for the -&v4l2-window; chromakey field. - - - - - - For destructive Video -Overlays applications must initialize this field. For -Video Output Overlays the driver must return -a valid format. - - - - - - Usually this is an RGB format (for example -V4L2_PIX_FMT_RGB565) -but YUV formats (only packed YUV formats when chroma keying is used, -not including V4L2_PIX_FMT_YUYV and -V4L2_PIX_FMT_UYVY) and the -V4L2_PIX_FMT_PAL8 format are also permitted. The -behavior of the driver when an application requests a compressed -format is undefined. See for information on -pixel formats. - - - - &v4l2-field; - field - Drivers and applications shall ignore this field. -If applicable, the field order is selected with the &VIDIOC-S-FMT; -ioctl, using the field field of -&v4l2-window;. - - - - __u32 - bytesperline - Distance in bytes between the leftmost pixels in -two adjacent lines. - - - This field is irrelevant to -non-destructive Video -Overlays.For destructive Video -Overlays both applications and drivers can set this field -to request padding bytes at the end of each line. Drivers however may -ignore the requested value, returning width -times bytes-per-pixel or a larger value required by the hardware. That -implies applications can just set this field to zero to get a -reasonable default.For Video Output -Overlays the driver must return a valid -value.Video hardware may access padding bytes, therefore -they must reside in accessible memory. Consider for example the case -where padding bytes after the last line of an image cross a system -page boundary. Capture devices may write padding bytes, the value is -undefined. Output devices ignore the contents of padding -bytes.When the image format is planar the -bytesperline value applies to the largest -plane and is divided by the same factor as the -width field for any smaller planes. For -example the Cb and Cr planes of a YUV 4:2:0 image have half as many -padding bytes following each line as the Y plane. To avoid ambiguities -drivers must return a bytesperline value -rounded up to a multiple of the scale factor. - - - - __u32 - sizeimage - This field is irrelevant to -non-destructive Video Overlays. For -destructive Video Overlays applications must -initialize this field. For Video Output -Overlays the driver must return a valid -format.Together with base it -defines the framebuffer memory accessible by the -driver. - - - - &v4l2-colorspace; - colorspace - This information supplements the -pixelformat and must be set by the driver, -see . - - - - __u32 - priv - Reserved for additional information about custom -(driver defined) formats. When not used drivers and applications must -set this field to zero. - - - -
- - - Frame Buffer Capability Flags - - &cs-def; - - - V4L2_FBUF_CAP_EXTERNOVERLAY - 0x0001 - The device is capable of non-destructive overlays. -When the driver clears this flag, only destructive overlays are -supported. There are no drivers yet which support both destructive and -non-destructive overlays. - - - V4L2_FBUF_CAP_CHROMAKEY - 0x0002 - The device supports clipping by chroma-keying the -images. That is, image pixels replace pixels in the VGA or video -signal only where the latter assume a certain color. Chroma-keying -makes no sense for destructive overlays. - - - V4L2_FBUF_CAP_LIST_CLIPPING - 0x0004 - The device supports clipping using a list of clip -rectangles. - - - V4L2_FBUF_CAP_BITMAP_CLIPPING - 0x0008 - The device supports clipping using a bit mask. - - - V4L2_FBUF_CAP_LOCAL_ALPHA - 0x0010 - The device supports clipping/blending using the -alpha channel of the framebuffer or VGA signal. Alpha blending makes -no sense for destructive overlays. - - - V4L2_FBUF_CAP_GLOBAL_ALPHA - 0x0020 - The device supports alpha blending using a global -alpha value. Alpha blending makes no sense for destructive overlays. - - - V4L2_FBUF_CAP_LOCAL_INV_ALPHA - 0x0040 - The device supports clipping/blending using the -inverted alpha channel of the framebuffer or VGA signal. Alpha -blending makes no sense for destructive overlays. - - - V4L2_FBUF_CAP_SRC_CHROMAKEY - 0x0080 - The device supports Source Chroma-keying. Framebuffer pixels -with the chroma-key colors are replaced by video pixels, which is exactly opposite of -V4L2_FBUF_CAP_CHROMAKEY - - - -
- - - Frame Buffer Flags - - &cs-def; - - - V4L2_FBUF_FLAG_PRIMARY - 0x0001 - The framebuffer is the primary graphics surface. -In other words, the overlay is destructive. [?] - - - V4L2_FBUF_FLAG_OVERLAY - 0x0002 - The frame buffer is an overlay surface the same -size as the capture. [?] - - - The purpose of -V4L2_FBUF_FLAG_PRIMARY and -V4L2_FBUF_FLAG_OVERLAY was never quite clear. -Most drivers seem to ignore these flags. For compatibility with the -bttv driver applications should set the -V4L2_FBUF_FLAG_OVERLAY flag. - - - V4L2_FBUF_FLAG_CHROMAKEY - 0x0004 - Use chroma-keying. The chroma-key color is -determined by the chromakey field of -&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see -and - . - - - There are no flags to enable -clipping using a list of clip rectangles or a bitmap. These methods -are negotiated with the &VIDIOC-S-FMT; ioctl, see and . - - - V4L2_FBUF_FLAG_LOCAL_ALPHA - 0x0008 - Use the alpha channel of the framebuffer to clip or -blend framebuffer pixels with video images. The blend -function is: output = framebuffer pixel * alpha + video pixel * (1 - -alpha). The actual alpha depth depends on the framebuffer pixel -format. - - - V4L2_FBUF_FLAG_GLOBAL_ALPHA - 0x0010 - Use a global alpha value to blend the framebuffer -with video images. The blend function is: output = (framebuffer pixel -* alpha + video pixel * (255 - alpha)) / 255. The alpha value is -determined by the global_alpha field of -&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see -and . - - - V4L2_FBUF_FLAG_LOCAL_INV_ALPHA - 0x0020 - Like -V4L2_FBUF_FLAG_LOCAL_ALPHA, use the alpha channel -of the framebuffer to clip or blend framebuffer pixels with video -images, but with an inverted alpha value. The blend function is: -output = framebuffer pixel * (1 - alpha) + video pixel * alpha. The -actual alpha depth depends on the framebuffer pixel format. - - - V4L2_FBUF_FLAG_SRC_CHROMAKEY - 0x0040 - Use source chroma-keying. The source chroma-key color is -determined by the chromakey field of -&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see and . -Both chroma-keying are mutual exclusive to each other, so same -chromakey field of &v4l2-window; is being used. - - - -
- - - - &return-value; - - - - EPERM - - VIDIOC_S_FBUF can only be called -by a privileged user to negotiate the parameters for a destructive -overlay. - - - - EBUSY - - The framebuffer parameters cannot be changed at this -time because overlay is already enabled, or capturing is enabled -and the hardware cannot capture and overlay simultaneously. - - - - EINVAL - - The ioctl is not supported or the -VIDIOC_S_FBUF parameters are unsuitable. - - - - - - - -- cgit v1.2.1