188 lines
6.5 KiB
Groff
188 lines
6.5 KiB
Groff
.\" $NetBSD: video.9,v 1.5 2009/03/12 12:37:18 joerg 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 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.
|