Aros/Developer/VHI

Introduction 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 Examples Reference 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 #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