.\"	$NetBSD: video.9,v 1.7 2014/03/18 18:20:40 riastradh Exp $
.\"
.\" Copyright (c) 2008 Patrick Mahoney
.\" All rights reserved.
.\"
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd July 24, 2008
.Dt VIDEO 9
.Os
.Sh NAME
.Nm video
.Nd interface between low and high level video drivers
.Sh SYNOPSIS
.In dev/video_if.h
.Ft device_t
.Fn video_attach_mi "const struct video_hw_if *hw_if" "device_t hw_dev"
.Ft void
.Fn video_submit_payload "device_t vl_dev" "const struct video_payload *payload"
.Sh DESCRIPTION
The video device driver is divided into a high level, machine
independent layer, and a low level hardware dependent layer.
The interface between these is the
.Fa video_hw_if
structure function pointers called by the video layer, and video layer
functions called by the hardware driver.
.Pp
The high level video driver attaches to the low level driver
when the latter calls
.Fa video_attach_mi .
The
.Fa video_hw_if
struct is as shown below.
.Fa dev
is the device struct for the hardware device.
Return value is the video layer device.
.Bd -literal
struct video_hw_if {
	int	(*open)(void *, int); /* open hardware */
	void	(*close)(void *);     /* close hardware */

	const char *	(*get_devname)(void *);

	int	(*enum_format)(void *, uint32_t, struct video_format *);
	int	(*get_format)(void *, struct video_format *);
	int	(*set_format)(void *, struct video_format *);
	int	(*try_format)(void *, struct video_format *);

	int	(*start_transfer)(void *);
	int	(*stop_transfer)(void *);

	int	(*control_iter_init)(void *, struct video_control_iter *);
	int	(*control_iter_next)(void *, struct video_control_iter *);
	int	(*get_control_desc_group)(void *,
					  struct video_control_desc_group *);
	int	(*get_control_group)(void *, struct video_control_group *);
	int	(*set_control_group)(void *, const struct video_control_group *);
};
.Ed
.Pp
The upper layer of the video driver allocates buffers for video
samples.
The hardware driver submits data to the video layer with
.Fa video_submit_payload .
.Fa vl_dev
is the video layer device returned by
.Fa video_attach_mi .
.Bd -literal
struct video_payload {
	const uint8_t	*data;
	size_t		size;
	int		frameno;
	bool		end_of_frame;
};
.Ed
.Bl -tag -width indent
.It Fa data
Pointer to the video data for this payload.
This may only be a
portion of the data in one video sample or frame.
.It Fa size
Size in bytes of the video data in this payload
.It Fa frameno
Frame number to which this payload belongs.
The hardware driver must toggle the frame number between 0 and 1
so the video layer can detect sample or frame boundaries.
.It Fa end_of_frame
Optional end of frame marker.
If the hardware layer sets this, the
video layer can immediately pass the completed sample or frame to
userspace rather than waiting for the next payload to toggle
.Fa frameno .
.El
.Sh HARDWARE-LAYER FUNCTIONS
The fields of
.Va video_hw_if
are described in some more detail below.
Some fields are optional and can be set to
.Dv NULL
if not needed.
.Bl -tag -width indent
.It Dv int open(void *hdl, int flags)
optional, is called when the video device is opened.
It should initialize the hardware for I/O.
Every successful call to
.Va open
is matched by a call to
.Va close .
Return 0 on success, otherwise an error code.
.It Dv void close(void *hdl)
optional, is called when the audio device is closed.
.It Dv const char * get_devname(void *hdl)
mandatory, returns a NUL-terminated string naming the device, e.g. a
vendor and product model name.
.It Dv int enum_format(void *hdl, uint32_t index, struct video_format *format);
mandatory, called with an
.Va index
from 0 to
.Va max_index \- 1 .
Fills
.Va format
with the format description at that index.
Returns 0 on success, otherwise an error code.
.It Dv int get_format(void *hdl, struct video_format *format)
mandatory, fills
.Va format
with the current video format.
There should be a default format so
this function works before and streaming has begun.
Returns 0 on success, otherwise an error code.
.It Dv int set_format(void *hdl, struct video_format *format)
mandatory, sets the format of the video stream based on
.Va format .
Fills
.Va format
with the actual format used which may not be the same as requested.
Returns 0 on success, otherwise an error code.
.It Dv int try_format(void *hdl, struct video_format *format)
optional, like
.Va set_format
but does not actually change the stream format, just checks what is
available.
Returns 0 on success, otherwise an error code.
.It Dv int start_transfer(void *hdl)
mandatory, starts the capture of video frames.
Incoming video data
must be submitted to the video layer with repeated calls to
.Fn video_submit_payload .
.It Dv int stop_transfer(void *hdl)
.It Dv int control_iter_init(void *hdl, struct video_control_iter *)
Does nothing at this time.
.It Dv int control_iter_next(void *hdl, struct video_control_iter *)
Does nothing at this time.
.It Dv int get_control_group(void *hdl, struct video_control_group *)
.It Dv int set_control_group(void *hdl, struct video_control_group *)
.El
.Sh SEE ALSO
.Xr video 4
.Sh AUTHORS
.An Patrick Mahoney Aq Mt pat@polycrystal.org
.Sh BUGS
Incomplete.
Only supports a single video capture stream.
Does not support output streams.
Format handling may change in the future.
Control handling may change.
Current design requires copying all incoming video data.