Cropping, composing and scaling

> + > + Cropping, composing and scaling > + > +Some video capture devices can sample a subsection of a picture and > +shrink or enlarge it to an image of arbitrary size. Next, the devices can > +insert the image into larger one. Some video output devices can crop part of an > +input image, scale it up or down and insert it at an arbitrary scan line and > +horizontal offset into a video signal. We call these abilities cropping, > +scaling and composing. > + > +On a video capture device the source is a video > +signal, and the cropping target determine the area actually sampled. The sink > +is an image stored in a memory buffer. The composing area specify which part s/specify/specifies/ > +of the buffer is actually written by the hardware. s/written/written to/ > +On a video output device the source is an image in a > +memory buffer, and the cropping target is a part of an image to shown on a s/shown/show/ or s/shown/be shown/ > +display. The sink is the display or the graphics screen. The application may > +select the part of display where the image should be displayed. The size and > +position of such a window is controlled by compose target. s/compose target/the compose target/ > +Rectangles for all cropping and composing targets are defined even if the > +device does not support neither cropping nor composing. Their size and position s/does not support/supports/ or s/neither cropping nor/cropping or/ > +will be fixed in such a case. If the device does not support scaling then the > +cropping and composing rectangles have the same size. > + > +

> + Selection targets > + > +

> + Cropping and composing targets > + > + > + > + > + > + Targets used by a cropping, composing and scaling > + process > + > + > + > +

> + > +

> + > + Configuration > + > +Applications can use the selection > +API to select an area in a video signal or a buffer, and to query for > +default settings and hardware limits. > + > +Video hardware can have various cropping, composing and scaling > +limitations. It may only scale up or down, support only discrete scaling > +factors, or have different scaling abilities in horizontal and vertical > +direction. Also it may not support scaling at all. At the same time the s/horizontal and vertical direction/the horizontal and vertical directions/ > +cropping/composing rectangles may have to be aligned, and both the source and > +the sink may have arbitrary upper and lower size limits. Therefore, as usual, > +drivers are expected to adjust the requested parameters and return the actual > +values selected. An application can control the rounding behaviour using +linkend="v4l2-sel-flags"> constraint flags . > + > +

> + > + Configuration of video capture > + > +See the figure for examples of the s/the figure/figure/ > +selection targets available for a video capture device. The targets should be > +configured according to the pipeline configuration rules for a capture device. Do we have such rules written somewhere ? > +It means that the cropping targets must be configured in prior to the composing > +targets. > + > +The range of coordinates of the top left corner, width and height of a > +area which can be sampled is given by the V4L2_SEL_CROP_BOUNDS s/a area which/areas that/ > + target. To support a wide range of hardware this specification does > +not define an origin or units. > + > +The top left corner, width and height of the source rectangle, that is > +the area actually sampled, is given by V4L2_SEL_CROP_ACTIVE s/by/by the/ > + target. It uses the same coordinate system as > +V4L2_SEL_CROP_BOUNDS . The active cropping area must lie completely > +inside the capture boundaries. The driver may further adjust the requested size > +and/or position according to hardware limitations. > + > +Each capture device has a default source rectangle, given by the > + V4L2_SEL_CROP_DEFAULT target. The center of this > +rectangle shall align with the center of the active picture area of the video > +signal, and cover what the driver writer considers the complete picture. > +Drivers shall reset the crop rectangle to the default when the driver is first s/reset the crop rectangle/set the active crop rectangle/ > +loaded, but not later. > + > +The composing targets refer to a memory buffer. The limits of composing > +coordinates are obtained using V4L2_SEL_COMPOSE_BOUNDS . > +All coordinates are expressed in pixels. The top/left corner is always point > + {0,0} . The width and height is equal to the image size > +specified using VIDIOC_S_FMT . We support sub-pixel cropping, but not sub-pixel composition. Can you remind me of the rationale for that ? > +The part of a buffer into which the image is inserted by the hardware is > +controlled by V4L2_SEL_COMPOSE_ACTIVE target. The s/by/by the/ > +rectangle's coordinates are also expressed in pixels. The composing rectangle > +must lie completely inside bounds rectangle. The driver must adjust the > +composing rectangle to fit to the bounding limits. Moreover, the driver can > +perform other adjustments according to hardware limitations. The application > +can control rounding behaviour using constraint > +flags . > + > +For capture devices the default composing rectangle is queried using > + V4L2_SEL_COMPOSE_DEFAULT and it is always equal to > +bounding rectangle. If they're always equal, why do we have two different targets ? :-) Maybe "is usually identical to" or "is most of the time identical to" would be better ? > +The part of a buffer that is modified by the hardware is given by > + V4L2_SEL_COMPOSE_PADDED . It contains all pixels defined > +using V4L2_SEL_COMPOSE_ACTIVE plus all padding data > +modified by hardware during insertion process. All pixel outside this rectangle s/All pixel/All pixels/ > +must not be changed by the hardware. The content of pixels > +that lie inside the padded area but outside active area is undefined. The > +application can use the padded and active rectangles to detect where the > +rubbish pixels are located and remove them if needed. How would an application remove them ? > + > +

> + > +

> + > + Configuration of video output > + > +For output devices targets and ioctls are used accordingly to the video s/accordingly/similarly/ > +capture case. The composing rectangle refer to insertion s/refer/refers/ or s/rectangle/rectangles/ s/insertion/the insertion/ > +of an image into a video signal. The cropping rectangles refer to a memory > +buffer. The targets are should be configured according to the pipeline s/are// > +configuration rules for a output device. It means that the compose targets must s/a output/an output/ > +be configured in prior to cropping targets. s/in prior to/before the/ > + > +The cropping targets refer to the memory buffer which contains an image s/which/that/ > +to be inserted into video signal or graphical screen. The limits of cropping s/into/into a/ > +coordinates are obtained using V4L2_SEL_CROP_BOUNDS . All > +coordinates are expressed in pixels. The top/left corner is always point > + {0,0} . The width and height is equal to the image size > +specified using VIDIOC_S_FMT ioctl. > + > +The top left corner, width and height of the source rectangle, that is > +the area from which pixels are processed by the hardware. The target identifier > +is V4L2_SEL_CROP_ACTIVE . Its coordinates are expressed s/. The target identifier is/, is given by/ > +in pixels. The active cropping area must lie completely inside the crop > +boundaries and the driver may further adjust the requested size and/or position > +according to hardware limitations. > + > +For output devices the default cropping rectangle is queried using > + V4L2_SEL_CROP_DEFAULT and it is always equal to cropping > +bounding rectangle. Same, comment maybe "is usually identical to the" or "is most of the time identical to the" would be better ? > + > +The part of a video signal or graphics display where the image is > +inserted by the hardware is controlled by V4L2_SEL_COMPOSE_ACTIVE s/by/by the/ > + target. The rectangle's coordinates are expressed driver dependant s/expressed/expressed in/ > +units. The only exception are digital outputs where the units are pixels. The > +composing rectangle must lie completely inside bounds rectangle. The driver s/bounds rectangle/the bounds rectangle/ > +must adjust the area to fit to the bounding limits. Moreover, the driver can > +perform other adjustments according to hardware limitations. > + > +The device has a default composing rectangle, given by the > +V4L2_SEL_COMPOSE_DEFAULT target. The center of this rectangle shall > +align with the center of the active picture area of the video signal, and cover > +what the driver writer considers the complete picture. Drivers shall reset the s/reset/set/ > +composing rectangle to the default one when the driver is first loaded. > + > +The devices may introduce additional content to video signal other then s/then/than/ > +an image from memory buffers. It includes borders around an image. However, > +such a padding area is very driver-dependant issue. Driver developers are s/ issue// (?) > +encouraged to keep padding rectangle equal to active one. The padding target > +is accessed by V4L2_SEL_COMPOSE_PADDED identifier. It s/by/by the/ > +must contain all pixels from V4L2_SEL_COMPOSE_ACTIVE s/from/from the/ > +target. > + > +

> + > +

> + > + Scaling control. > + > +An application can detect if scaling is performed by comparing width and s/width/the width/ > +height of rectangles obtained using V4L2_SEL_CROP_ACTIVE > +and V4L2_SEL_COMPOSE_ACTIVE targets. If these are not > +equal then the scaling is applied. The application can compute scaling ratios s/the scaling/scaling/ > +using these values. > + > +

> + > +

> + Examples > + > + Resetting the cropping parameters > + > + (A video capture device is assumed; change > +V4L2_BUF_TYPE_VIDEO_CAPTURE for other devices; change target to > + V4L2_SEL_COMPOSE_* family to configure composing > +area) > + > + > + > + &v4l2-selection; sel = { > + .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, > + .target = V4L2_SEL_CROP_DEFAULT, > + }; > + ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel); > + if (ret) > + exit(-1); > + sel.target = V4L2_SEL_CROP_ACTIVE; > + ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); > + if (ret) > + exit(-1); > + > + > + > + > + > + Simple downscaling > + Setting a composing area on output of size of at most > + half of limit placed at a center of a display. > + > + > + &v4l2-selection; sel = { > + .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, > + .target = V4L2_SEL_COMPOSE_BOUNDS, > + }; > + struct v4l2_rect r; > + > + ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel); > + if (ret) > + exit(-1); > + /* setting smaller compose rectangle */ > + r.width = sel.r.width / 2; > + r.height = sel.r.height / 2; > + r.left = sel.r.width / 4; > + r.top = sel.r.height / 4; > + sel.r = r; > + sel.target = V4L2_SEL_COMPOSE_ACTIVE; > + sel.flags = V4L2_SEL_SIZE_LE; > + ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); > + if (ret) > + exit(-1); > + > + > + > + > + > + Querying for scaling factors > + A video output device is assumed; change > +V4L2_BUF_TYPE_VIDEO_OUTPUT for other devices > + > + > + &v4l2-selection; compose = { > + .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, > + .target = V4L2_SEL_COMPOSE_ACTIVE, > + }; > + &v4l2-selection; crop = { > + .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, > + .target = V4L2_SEL_CROP_ACTIVE, > + }; > + double hscale, vscale; > + > + ret = ioctl(fd, &VIDIOC-G-SELECTION;, &compose); > + if (ret) > + exit(-1); > + ret = ioctl(fd, &VIDIOC-G-SELECTION;, &crop); > + if (ret) > + exit(-1); > + > + /* computing scaling factors */ > + hscale = (double)compose.r.width / crop.r.width; > + vscale = (double)compose.r.height / crop.r.height; > + > + > + > + > +

> + > +