Aros/Developer/VHI
< Aros
Introduction
[edit | edit source]- 1995 Innovative-web.de
- 1996 VHI driver
- 1997 fxScan
- 1998 VLRec NG
- 1999 fxPaint with OS 3.5 support
- 2000
- 2002 IOSPIRIT founded, take-over of Innovative.Web products
- 2003
- 2004 VHI Studio development stopped
- 2005
- 2007 In April, Felix Schwartz ended all Amiga software development
- 2026 AROS outline of VHI standard
Innovative and later IOSpirit and Felix Schwarz introduced this standard VHI aka Video Hardware Interface as there was no open standard for video captures on amigas with webcams or digital cameras leading to having to write their own interfacing software from usually hard to find hardware specs. Nowadays, bsd and linux have done some of the hardest work for us. Developers still have to convert/write a driver, that compatible with the VHI standard. VHI should support any source of video data and allow the usage of it in any application supporting the VHI standard. VHI adds another step between VHI drivers and applications, leading to two ways to make use of a video capture....
- Direct access of a video capture which needs a lot know-how about video and video formats in general (e.g. conversion YUV->RGB).
direct access of
VHI support the video hardware
Application -------------> VHI-driver ------------> Video Hardware
- Use of vhimaster.library for all the driver specific things but allows use of VHI support.
easy interface with fewer support direct access of the
commands, less source needed for VHI features video hardware
Application --------------> vhimaster.library ------------------> VHI driver ----------------> Video Hardware
A VHI-driver basically is a shared library and that it has only one function to call. A VHI-driver consists of methods and submethods, like how BOOPSI is defined.
An old driver should still be used with an updated versions of the VHI with new methods. An error-message should be displayed to show this method is not supported. Some of the special features of a board might be utilized by the added new methods.
Features
[edit | edit source]Examples
[edit | edit source]
Reference
[edit | edit source]vhi/vhi_api vhi/vhi_api
NAME
vhi_api - the whole API via one function
SYNOPSIS
result = vhi_api (method, submethod, attr, errcode, vhi_handle);
d0 d2 d3 d4 d5 d6
ULONG vhi_api (ULONG method, ULONG submethod, APTR attr,
ULONG *errcode, APTR vhi_handle);
FUNCTION
This function is the whole API of an VHI-driver and ensures maximum
flexibility for both developers and users.
INPUTS
method - The ID of the method. Can be one of the following:
VHI_METHOD_OPEN
VHI_METHOD_GET
VHI_METHOD_SET
VHI_METHOD_PERFORM
VHI_METHOD_CLOSE
For more information on these have a look at the
specs below.
submethod - The ID of the submethods of one of the above methods.
attr - Pointer to an attribute. This can e.g. be a structure.
errcode - If an error occurs (and be ready to handle it after every
call), the value of the error is written into the ULONG
pointed to here.
vhi_handle - Once a driver is initialised and has returned its
individual handle-pointer, this handle-pointer has
to be passed with every call as this parameter.
RETURNS
Either a numerical or a pointing result. If it is a pointer, don`t
forget to cast the ULONG-value.
vhi/--errormessages-- vhi/--errormessages--
ERROR MESSAGES
VHI can return an error with every call. You can find all possible
error-messages and the ways to react to them here.
VHI_ERR_UNKNOWN_METHOD - This method is unknown to the driver. Try
to do it otherwise and if this doesn`t work,
too, close the driver and inform the user,
that the driver isn`t fully implemented.
VHI_ERR_COULD_NOT_INIT - The board couldn`t be initialized. Close the
driver and inform the user. Suggest to the
user to check, whether it is defective.
VHI_ERR_NO_HARDWARE - The hardware required by this driver wasn`t
found. Close the driver and inform the user.
Suggest to the user to check, whether the
hardware is defective or whether it is
installed correctly.
VHI_ERR_NO_INPUT_DATA - There is no signal at the selected input. Bring
up a message to inform the user to either select
the correct input or to connect some source with
a signal.
VHI_ERR_ERR_WHILE_DIG - An error occured while getting the video data.
You may want to close the driver or bring up
a requester and let the user choose. In most
cases, this error only occurs, if there isn`t
enough memory.
VHI_ERR_OUT_OF_MEMORY - Not enough memory. Stop the current process
and inform the user. You may also want to close
the driver.
VHI_ERR_INTERNAL_ERROR - Internal driver error. Stop the current process
and inform the user. Let him choose, whether to
proceed or close the driver.
vhi/VHI_METHOD_OPEN vhi/VHI_METHOD_OPEN
NAME
VHI_METHOD_OPEN - open and initialize a driver and get its handle.
REQUIRES
none.
DESCRIPTION
For "users" and "developers":
The driver allocates memory for its individual handling structure and
returns a pointer to it, that you`ll then have to pass with every call.
IMPORTANT: Don`t open and close a driver for every frame you grab or
every change you make to the options. Not only that the options
are reset with every open/close but it is also the most
ineffective way of using a video-board. Open a driver, when
starting to use it and close it, when stopping to use it.
After opening, set all your options: There is no default-
option-state after opening a driver, that is common among
all VHI-drivers.
For "developers":
It`s only wise to store important data here, like e.g. color or
grayscale mode, interlace or other board-dependant flags and their
status. You may use any self-created structure here.
CALLING EXAMPLE
struct Library *VHIBase=NULL;
APTR vhi_handle;
BOOL open_vhi_driver(char *name)
{
ULONG errcode;
if (VHIBase = OpenLibrary(name,0L))
{
vhi_handle = (APTR) vhi_api (VHI_METHOD_OPEN,
NULL,
NULL,
&errcode,
NULL);
if (errcode)
{
handle_vhi_error (errcode);
return(decide_whether_vhi_error_keeps_you_from_boardusage(errcode));
}
return(TRUE);
}
else
{
return(FALSE);
}
}
SUBMETHODS
none.
vhi/VHI_METHOD_GET VHI/VHI_METHOD_GET
NAME
VHI_METHOD_GET - Get the status of an option.
REQUIRES
vhi_handle-pointer of an opened VHI-driver.
DESCRIPTION
This method and its submethods return you information
about the board and the current settings. Most of the
submethods described here are also settable. For settable
methods, see VHI_METHOD_SET.
SUBMETHODS
VHI_CARD_NAME - returns a pointer to a null-terminated string
containing the name of the board. The memory
has to be allocated by the driver via AllocVec
and has to be freed by the application via FreeVec.
VHI_CARD_MANUFACTURER - as VHI_CARD_NAME, returns the name of the
manufacturer of the board
VHI_CARD_DRIVERAUTHOR - as VHI_CARD_NAME, returns the name of the
author of the driver.
VHI_CARD_DRIVERVERSION - returns the version of the driver as
an unsigned long.
VHI_CARD_DRIVERREVISION - returns the revision of the driver as
an unsigned long.
VHI_CARD_REVISION - returns the revision of the board (not the
driver!!) as an unsigned long.
VHI_CARD_VERSION - returns the version of the board (not the
driver!!) as an unsigned long.
VHI_SUPPORTED_MODES - returns a combination of mode-flags. Defined
modes for this submethod are:
VHI_MODE_COLOR
VHI_MODE_GRAYSCALE
If the board supports both grayscale- and
color-digitizing, return
VHI_MODE_COLOR|VHI_MODE_GRAYSCALE
VHI_NUMBER_OF_INPUTS - returns the number of inputs of the board
as an unsigned long.
VHI_NAME_OF_INPUT - returns the name of the inputnumber passed as
attr (driver-author: cast to ULONG before!) in
the same way, that e.g. VHI_CARD_NAME was
returned.
VHI_SUPPORTED_OPTIONS - many boards have a varity of special features
and filters implemented in hardware. The result
of this submethod is an unsigned long containig
the combination of VHI_OPT-flags, wheras the
following are supported:
VHI_OPT_LUMINANCE - a filter to improve
luminance-quality
VHI_OPT_CHROMINANCE - a filter to improve
chrominance-quality
VHI_OPT_NOISE - a filter to reduce noise in
the digitized results
VHI_OPT_VIDEOREC - a filter to handle input
from video-recorders with
a bad sync-signal
VHI_OPT_NTSCPAL - The board supports switching
between both NTSC and PAL
(NOTE: Which are implemented
is another thing and is
returned by
VHI_SUPPORTED_VIDEOFORMATS)
VHI_OPT_INTERLACE - interlace-mode supported.
Interlace in the means of
returning a full picture
consisting of two half-pic
frames.
VHI_OPT_INPUT - the input of the board can
be changed (only makes sense,
if there is more than one
input to choose from.
An application should only provide the user
with options, that can be changed and that
are supported by a driver. An easy way to
do this, is to display all elements and
disable the unsupported ones. A more user-
friendly way is to simply not include these
options for choosing.
VHI_SUPPORTED_VIDEOFORMATS - result is an unsigned long containing
a combination of videoformats to choose
from. Currently, the following standards
are supported:
VHI_METHOD_PAL
VHI_METHOD_NTSC
VHI_METHOD_SECAM
VHI_METHOD_PAL60
If a driver supports NTSC and PAL, it
returns VHI_FORMAT_PAL|VHI_FORMAT_NTSC.
Please use VHI_METHOD_SET/VHI_VIDEOFORMAT
to set the videoformat instead of using
VHI_METHOD_SET/VHI_OPTIONS/VHI_OPT_NTSCPAL.
VHI_COLOR_MODE - result is an unsigned long. If it is set to one (1),
the color-mode is currently active, if it is set
to zero (0), it is set to grayscale.
VHI_MAXIMUM_SIZE - doesn`t have a "result". Pass a pointer
to a vhi_size-structure as attr-parameter.
The structure will then be filled with the
currently correct information about the
maximum possible size and hardware-features
like cropping and scaling.
NOTE: This information can (and most likely
will) change when switching from color
to grayscale, from NTSC to PAL or vice
versa!
Explanation of the vhi_size-elements in this
context:
struct vhi_size
{
ULONG max_width; // Maximum Width
ULONG max_height; // Maximum Height
BOOL fixed; // Can`t be
// changed = TRUE (no cropping)
BOOL scalable; // Driver/Board supports
// internal scaling
};
For an explanation of "fixed" and "scalable" in
context, see VHI_METHOD_PERFORM/VHI_DIGITIZE_PICTURE.
Please also note, that max_height has to be returned
for interlace-mode (even, if it not active) and not
for half-pic frames.
VHI_TRUSTME_MODE - This returns the status of the trustme-mode. See
VHI_METHOD_SET/VHI_TRUSTME_MODE for more details.
VHI_TRUSTME_SIZE - Pass a vhi_dimensions-structure as attr here. It
is then filled with the information. For more
information about this structure, see
VHI_METHOD_PERFORM/VHI_DIGITIZE_PICTURE. For more
information about the trustme-mode, see
VHI_METHOD_SET/VHI_TRUSTME_MODE.
OTHER METHOD - for developers: If your drivers gets another method
than the above and your driver doesn`t support it,
return a VHI_ERR_UNKNOWN_METHOD as errorcode. Please
don`t do this the wrong way:
errorcode = VHI_ERR_UNKNOWN_METHOD;
but the right way:
*errorcode = VHI_ERR_UNKNOWN_METHOD;
vhi/VHI_METHOD_SET vhi/VHI_METHOD_SET
NAME
VHI_METHOD_SET - Change the status of an option.
REQUIRES
vhi_handle-pointer of an opened VHI-driver.
DESCRIPTION
This method and its submethods change the status of options
and some also return information about the board and the current
settings. Most of the submethods described here are also "getable".
For "getable" methods, see VHI_METHOD_GET.
SUBMETHODS
VHI_OPTIONS - Change/Set one of the options described in
VHI_METHOD_GET/VHI_SUPPORTED_OPTIONS. For
this, pass an initialized vhi_setoptions-
structure as attr, whereas the element
"option" contains one of the following
options (enable is always 1, disable is
always 0):
VHI_OPT_LUMINANCE - enable/disable filter to improve
luminance-quality
VHI_OPT_CHROMINANCE - enable/disable filter to improve
chrominance-quality
VHI_OPT_NOISE - enable/disable filter to reduce noise
in the digitized results
VHI_OPT_VIDEOREC - enable/disable filter to handle
input from video-recorders with
a bad sync-signal
VHI_OPT_NTSCPAL - enable/disable NTSC-mode:
If set to 1, NTSC is chosen,
if set to 0, PAL is chosen.
Please use
VHI_METHOD_SET/VHI_VIDEOFORMAT
to set the videoformat instead of
using this method as otherwise
SECAM and PAL60 can`t be supported
by your application!
VHI_OPT_INTERLACE - enable/disable interlace-mode.
Interlace in the means of
returning a full picture
consisting of two half-pic
frames.
VHI_OPT_INPUT - Select the input, whereas the
first input is 0, the last one
VHI_METHOD_GET/VHI_NUMBER_OF_INPUTS-1.
VHI_COLOR_MODE - pass a BOOL as attr. If 1, color-mode is activated,
if 0, grayscale-mode is activated.
VHI_TRUSTME_MODE - This returns the status of the trustme-mode. Pass a one (1)
in attr to enable it and a zero (0) to disable it. BY
DEFAULT IT IS DISABLED BY THE DRIVER! The trustme-mode
allows you to set the size for digitizing once and not
having to pass correct information with every call of
VHI_METHOD_PERFORM/VHI_DIGITIZE_PICTURE. For best
performance first try to check, whether the driver
reports an error when calling this function and if not,
use this mode, as it saves some CPU-time.
VHI_TRUSTME_SIZE - Pass the vhi_dimensions-structure as attr here. For
more information about this structure, see
VHI_METHOD_PERFORM/VHI_DIGITIZE_PICTURE
For more information about the trustme-mode,
see VHI_TRUSTME_MODE.
VHI_VIDEOFORMAT - Pass the VHI_FORMAT-ID of the input-videosignal here.
You can get a combination of bits which specifiy which
videoformats are supported via VHI_METHOD_GET/
VHI_SUPPORTED_VIDEOFORMATS. This way you can switch
between different videoformats like NTSC and PAL.
OTHER METHOD - for developers: If your drivers gets another method
than the above and your driver doesn`t support it,
return a VHI_ERR_UNKNOWN_METHOD as errorcode. Please
don`t do this the wrong way:
errorcode = VHI_ERR_UNKNOWN_METHOD;
but the right way:
*errorcode = VHI_ERR_UNKNOWN_METHOD;
vhi/VHI_METHOD_PERFORM vhi/VHI_METHOD_PERFORM
NAME
VHI_METHOD_PERFORM - Perform an action.
REQUIRES
vhi_handle-pointer of an opened VHI-driver.
DESCRIPTION
This method and its submethods actually *perform* something,
like digitizing or checking the correctness of the values passed
to the digitize-method.
SUBMETHODS
VHI_CHECK_DIGITIZE_SIZE - this method checks the correctness
of the values stored in a vhi_dimensions-
structure, that is lateron element of
the vhi_digitize-structure. This is especially
useful, if your program supports realtime-
changing of the limits (cropping) via a
slider. VLRec NG is an example for such a
program. Pass a vhi_dimensions-structure
as attr and you get the corrected values
in the same structure after the call has
been finished. There is no "result" though.
VHI_DIGITIZE_PICTURE - this method is the most important one in the
whole VHI-driver: It digitizes a picture and
returns it. Pass a vhi_digitize-structure as
parameter. The structure`s elements have the
following meaning:
dim - this is a vhi_dimensions-structure,
description follows later.
custom_memhandling - if you don`t want the
driver to use standard
exec/AllocVec and
exec/FreeVec and other
memory-allocation-
functions instead,
set this to TRUE.
This function has
been defined in order
to make VHI compatible
with PPC-supporting
applications.
CstAllocVec - Set the function-pointer to
a memory-allocation-function
of the format
APTR myalloc (ULONG size, ULONG flags)
here, whereas all exec-flags have
to be supported. Only set this,
if custom_memhandling is TRUE.
CstFreeVec - Set the function-pointer to
a memory-freeing-function
of the format
APTR myfree (APTR mem)
here, if custom_memhandling is
TRUE.
Following now the dimensions-structure:
x1, y1 - upper, left corner of the area to
digitize. Has to be within the allowed
area returned by VHI_MAXIMUM_SIZE.
x2, y2 - lower, right corner of the area to
digitize. Has to be within the allowed
aread returned by VHI_MAXIMUM_SIZE.
dst_width, dst_height - If you would like the
data to be returned
scaled, if possible in
harware (for developers:
Don`t integrate software-
scaling!), set these
values. Set both of them
to zero, if you don`t
want the image to be
scaled, but in original
size.
As for x1,y1 and x2,y2:
Imagine a virtual screen that has the size of
the values returned by VHI_MAXMIMUM_SIZE. Now
you are "cutting out" the area between x1,y1
and x2,y2: It`s cropping a part of the entire
input-signal.
What has to happen within a driver, when this
method is called:
First of all (VERY important) have a look
at custom_memhandling, this might look like
this:
APTR (* CstAllocVec) (ULONG size, ULONG flags);
void (* CstFreeVec) (APTR mem);
/* Mem Handling */
CstAllocVec = AllocVec;
CstFreeVec = FreeVec;
if (digi->custom_memhandling)
{
CstAllocVec = digi->CstAllocVec;
CstFreeVec = digi->CstFreeVec;
}
Second thing is to look, whether the trustme-mode
is active. If yes, set the dimension-infos passed
via VHI_TRUSTME_SIZE in the vhi_digitize.dim -
structure. If no, make an internal call to
check the correctness of the data. This might
look like this:
vhi_method_perform (VHI_CHECK_DIGITIZE_SIZE,
&digi->dim, &err,
hs);
Third thing to do is to check, whether interlace-
mode is set or not. If interlace mode is NOT set,
divide the y2 and y1-coordinates by two, as the
application always looks at the driver as if only
interlace was available. This makes handling for
the application easier and is only some lines of
sourcecode for the programmer of the driver.
Now the real digitizing-process begins:
Allocate memory for an vhi_image-structure using
CstAllocVec, set width (img->width) and height
(img->height), whether the image was scaled (img->
scaled) in hardware and in which format you plan
to return the image-data. This can be one of the
following:
VHI_GRAYSCALE_8 - one byte per pixel,
return pointer in img->
chunky
VHI_RGB_24 - three bytes per pixel
return pointer in img->
chunky
VHI_YUV_411 - 12 bits per pixel
return pointer to the
y, u and v components
in img->y, img->u, img->v
VHI_YUV_422 - 16 bits per pixel
return pointer to the
y, u and v components
in img->y, img->u, img->v
VHI_YUV_444 - 24 bits per pixel
return pointer to the
y, u and v components
in img->y, img->u, img->v
When allocating the memory for y, u and v, add 16
to the number of bytes to allocate and allocate it
via CstAllocVec. When finally digitizing a picture,
pass LONGWORDALIGN(img->y), etc. to your internal
digitize-function to longword-align data in memory.
If you don`t do this, the program using your driver
will produce bad results. However, in the structure,
fill in the REAL pointers to the REAL adresses as
otherwise, bad results and crashes will follow.
When returning data in VHI_RGB_24 or VHI_GRAYSCALE_8-
modes, you don`t have to use the LONGWORDALIGN-macro.
vhi/VHI_METHOD_CLOSE vhi/VHI_METHOD_CLOSE
NAME
VHI_METHOD_CLOSE - close the driver and free all ressources
REQUIRES
Opened VHI-driver.
DESCRIPTION
This call frees all internally allocated memory. The vhi_handle
has to be passed as the vhi_handle-parameter.
SUBMETHODS
none.
headers
[edit | edit source]#ifndef _VHI_H
#define _VHI_H 1
/* Needed to get the correct adress for Y, U, V-data */
#define LONGWORDALIGN(addr) (((((ULONG) (addr))+8) >> 2L) << 2L)
/* Methods */
#define VHI_METHOD_OPEN 1L
#define VHI_METHOD_CLOSE 2L
#define VHI_METHOD_SET 3L
#define VHI_METHOD_GET 4L
#define VHI_METHOD_PERFORM 5L
/* Get & Set - Methods */
#define VHI_CARD_NAME 1L
#define VHI_CARD_MANUFACTURER 2L
#define VHI_CARD_REVISION 3L
#define VHI_CARD_VERSION 4L
#define VHI_CARD_DRIVERAUTHOR 5L
#define VHI_SUPPORTED_MODES 6L
#define VHI_NUMBER_OF_INPUTS 7L
#define VHI_NAME_OF_INPUT 8L
#define VHI_SUPPORTED_OPTIONS 9L
#define VHI_SUPPORTED_VIDEOFORMATS 10L
#define VHI_MAXIMUM_SIZE 11L
#define VHI_OPTIONS 12L
#define VHI_VIDEOFORMAT 13L
#define VHI_COLOR_MODE 14L
#define VHI_TRUSTME_MODE 15L
#define VHI_TRUSTME_SIZE 16L
#define VHI_CARD_DRIVERVERSION 17L
#define VHI_CARD_DRIVERREVISION 18L
/* Options */
#define VHI_OPT_LUMINANCE 1L
#define VHI_OPT_CHROMINANCE 2L
#define VHI_OPT_NOISE 4L
#define VHI_OPT_VIDEOREC 8L
#define VHI_OPT_NTSCPAL 16L
#define VHI_OPT_INTERLACE 32L
#define VHI_OPT_INPUT 64L
/* Video Formats - IDs (bitwise combination) */
#define VHI_FORMAT_PAL 1L
#define VHI_FORMAT_NTSC 2L
#define VHI_FORMAT_SECAM 4L
#define VHI_FORMAT_PAL60 8L
/* Performable methods */
#define VHI_CHECK_DIGITIZE_SIZE 1L
#define VHI_DIGITIZE_PICTURE 2L
/* Modes to get digitized results */
#define VHI_MODE_COLOR 1L
#define VHI_MODE_GRAYSCALE 2L
/* Types of vhi_images */
#define VHI_GRAYSCALE_8 1L
#define VHI_RGB_24 2L
#define VHI_YUV_411 3L
#define VHI_YUV_422 4L
#define VHI_YUV_444 5L
/* Error-Messages */
#define VHI_ERR_UNKNOWN_METHOD 1L // Means: This method is unknown
#define VHI_ERR_COULD_NOT_INIT 2L // Means: The board couldn`t be initialized
#define VHI_ERR_NO_HARDWARE 3L // Means: The hardware required by this driver wasn`t found
#define VHI_ERR_NO_INPUT_DATA 4L // Means: There is no signal at the selected input
#define VHI_ERR_ERR_WHILE_DIG 5L // Means: An error occured while getting the video data
#define VHI_ERR_OUT_OF_MEMORY 6L // Means: Not enough memory
#define VHI_ERR_INTERNAL_ERROR 7L // Means: Internal driver error
/* Structures */
struct vhi_setoptions
{
ULONG option; // The ID of the option
ULONG value; // The new value for this option
};
struct vhi_dimensions
{
ULONG x1; // The rectangle to grab from the
ULONG y1; // full picture
ULONG x2;
ULONG y2;
ULONG dst_width; // The size to scale the data to.
ULONG dst_height;
};
struct vhi_size
{
ULONG max_width; // Maximum Width
ULONG max_height; // Maximum Height
BOOL fixed; // Can`t be changed = TRUE (no cropping)
BOOL scalable; // Driver/Board supports internal scaling
};
struct vhi_image
{
APTR chunky; // For grayscale or RGB
APTR y; // The Y
APTR u; // The U
APTR v; // The V-data
ULONG width; // Width of the image
ULONG height; // Height of the image
ULONG type; // e.g. VHI_YUV_422
BOOL scaled; // Image has been scaled internally
};
struct vhi_digitize
{
struct vhi_dimensions dim;
BOOL custom_memhandling;
APTR (* CstAllocVec) (ULONG size, ULONG flags); // Provide function-pointers to use
void (* CstFreeVec) (APTR mem); // in case this is important (e.g. for
// correct alignment ..)
};
#endif