|  | VISION Documentation (VAPI) |  | Last update 08/04/18
| RASTER INTERFACE |

Summary
Interface prefix | Ra
Number of functions | 16
Description | Set of functions allowing to handle image rasters under different formats (bit-plane, True Color, ATARI formats, specific, standard...).

Prototype | void cdecl RaImgWhite(MFDB *img)
Parameters | [IN/OUT] img: pointer on the image to process
Return | None
Description | Initialise an image raster with the white colour. The expected format is the ATARI format. In palette mode (img->fd_nplanes <= 8), the raster is initialised with bits set to 0 (TOS/VID index = 0), the 0 index of the palette is usually set on the white colour.
Comments | This function processes the transformation "in place".
VAPI version | 1.00 or greater

Prototype | long cdecl RaIs15Bits(void)
Parameters | None
Return | 0: True Color format on 16 bits or number of bits of the graphic resolution not equal to 16 1: Number of planes of the graphic resolution on 16 bits but pixel coding on 15 bits (5 per component)
Description | Indicates whether the True Color coding of the graphic resolution is on 15 or 16 bits

Comments

In cases where it is useful to know whether the number of bits of coding for the green component is on 5 or 6 bits, it is possible, using this function, to know whether all the 16 bits of the True Color mode on 16 planes are used (green component is then coded on 6 bits instead of 5 and RaIs51Bits returns 0) or only 15 bits are used (green component is then coded on 5 bits and RaIs15Bits returns 1)

VAPI version | 1.00 or greater

Prototype | void cdecl RaTCConvert(MFDB *img)
Parameters | [IN/OUT] img: pointer on the image to process
Return | None
Description | Transforms a True Color raster of the specific format of the graphic card to a True Color raster in ATARI format
Comments | This function processes the transformation "in place". If VISION recognises that the machine specific format is the ATARI format, the function returns immediately, without any processing. This function is the reverse of RiTCInvConvert
VAPI version | 1.00 or greater

Prototype | void cdecl RaTCInvConvert(MFDB *img)
Parameters | [IN/OUT] img: pointer on the image to process
Return | None
Description | Transforms a True Color raster in ATARI format to a True Color raster in the format specific to the graphic card
Comments | This function processes the transformation "in place". If VISION recognises that the machine specific format is the ATARI format, the function returns immediately, without any processing. This function is the reverse of RiTCInvConvert
VAPI version | 1.00 or greater

Prototype | void cdecl RaInd2RasterInit(MFDB *img, long width)
Parameters | [IN/OUT] img: pointer on the image to process [IN] width: maximum width (in pixels). width cannot be greater than 32767. Coding on a 32 bits integer is only for ensuring compatibility with 32 bits compilers.
Return | None
Description | Prepares index transfer operatios to an image raster in ATARI format.
Comments | The width may seem redundant with img->fd_w but it is there because VISION always set img->fd_w to a multiple of 16 (internal optimisations). Thus, width allows not to be limited to a width multiple of 16 pixels. Interesting : if width is a multiple of 16, the RaInd2Raster function will be much faster!
VAPI version | 1.00 or greater

Prototype | void cdecl RaInd2Raster(unsigned char*indexes, long nb_indexes)
Parameters | [IN] indexes: pointer on the TOS table indexes to convert to the raster previously initialised with the RaInd2RasterInit function [IN] nb_indexes: Number of indexes in the table pointed by indexes
Return | None
Description | Converts TOS indexes in raster bit-plane data

Comments

Once the initialisation is done by the RaInd2RasterInit functio, this function may be called as much as wanted to transform the data flow (TOS indexes) to the image raster. VAPI memorises the last position in the raster. For instance: Vapi->RaInd2RasterInit( img, wished_width ) ;
for ( y = 0; y < img->fd_h; y++ )
{
GetTosIndexes( y, tab_indexes, &nb_indexes ) ; /* Get TOS indexes for line y */
Vapi->RaInd2Raster( tab_indexes, nb_indexes ) ; /* Send to the ATARI bit-plane format raster */
}

VAPI version | 1.00 or greater

Prototype | void cdecl RaRaster2Ind(short *pt_bitplan, long nb_pts, long nb_planes, unsigned char *tos_indexes)

Parameters

[IN] pt_bitplan: pointer on the beginning of raster data to convert (start with a multiple of 16 pixels)
[IN] nb_pts: Number of points to convert
[IN] nb_planes: Number of planes of the image raster. nb_planes can only take values 1, 2, 4, or 8. Coding on a 32 bits integer is only for ensuring compatibility with 32 bits compilers.
[OUT] tos_indexes: pointer on the TOS indexes table receiving the data (must be dimensioned to nb_pts bytes)

Return | None
Description | Converts bit-plane data from the raster to TOS indexes
Comments | Reverse function of RaInd2Raster
VAPI version | 1.00 or greater

Prototype | unsigned char *cdecl RaGetTOS2VDIArray(long nb_planes)
Parameters | [IN] nb_planes: Number of plans. nb_planes can only take values 1, 2, 4, or 8. Coding on a 32 bits integer is only for ensuring compatibility with 32 bits compilers.
Return | Pointeur on the conversion table TOS index --> VDI index
Description | Get the matching table between TOS and VDI indexes, for a given number of planes
Comments | Reverse function of RaGetVDI2TOSArray
VAPI version | 1.00 or greater

Prototype | unsigned char *cdecl RaGetVDI2TOSArray(long nb_planes)
Parameters | [IN] nb_planes: Number of planes. nb_planes can only take values 1, 2, 4, or 8. Coding on a 32 bits integer is only for ensuring compatibility with 32 bits compilers.
Return | Pointeur on the conversion table VDI index --> TOS index
Description | Get the matching table between VDI and TOS indexes, for a given number of planes
Comments | Reverse function of RaGetTOS2VDIArray
VAPI version | 1.00 or greater

Prototype | unsigned long *cdecl RaGetImgSize(long width, long height, long nplanes)
Parameters | [IN] width : Image width in pixels number [IN] height : Image height in pixels number [IN] nplanes : Number of planes per pixel 32bit variable sizes is just here for 32bit compilers compatibility.
Return | The required memory size, in bytes, to hold the image
Description | Used to know the image size, the 16 pixels alignement taken into account
Comments |
VAPI Version | 1.02 or greater

Prototype | long cdecl RaRasterAlloc(MFDB *raster)
Parameters | [IN/OUT] raster : VDI structure defining an image
Return | 0 : OK, memory has been allocated (pointed out by fd_addr field of MFDB structure) != 0 : Error (not enough memory)
Description | Allocate an image based on its definition (fd_w, fd_h and fd_nplanes MFDB structure fields).
Remarks | Upon success, fd_addr points to image data (not initialized), else fd_addr is set to NULL. fd_wdwidth is updated, other fileds remain unchanged.
VAPI Version | 1.02 or greater

Prototype | void cdecl RaRasterFree(MFDB *raster)
Parameters | [IN/OUT] raster : VDI structure defining an image
Return | None
Description | Free previously allocated memory by RaRasterAlloc
Remarks | All MFDB fileds are set to zero after memory being freed.
VAPI Version | 1.02 or greater

Prototype | void cdecl RaTC15RemapColors(REMAP_COLORS *rc)
Parameters | [IN] rc : Pointer to a REMAP_COLORS structure defining elementary color changes, first pixel to change and number of pixels to operate on.
Return | None.

Description

Change the current color spreading of a 15bit True Color image. red, green and blue fields of REMAP_COLORS shall point to arrays of 32 (32 = 2^5) elements, each element being the value to substitute at this array index for instance the formula:
red[i] = i ; (0 <= i < 32) does not change anything (i being replaced by i).
Warining ! The new value to substitute shall belong to range [0,31].
Another example:: rise lighting by 100% for all compounds:
new_val = i * 2 ;
if ( new_val > 31) new_val = 31 ; /* Important ! */
red[i] = green[i] = blue[i] = new_val ;

Remarks | This function operates on Machine specific format ! You shall not call RaTCConvert or RaTCInvConvert.
VAPI Version | 1.03 or greater

Prototype | void cdecl RaTC16RemapColors(REMAP_COLORS *rc)
Parameters | [IN] rc : Pointer to a REMAP_COLORS structure defining elementary color changes, first pixel to change and number of pixels to operate on.
Return | None

Description

Change the current color spreading of a 16bit True Color image. red, green and blue fields of REMAP_COLORS shall point to arrays of 32 (32 = 2^5) elements for red and blue compounds and 64 (64=2^6) for green compound. Each element being the value to substitute at this array index for instance the formula:
red[i] = i ; (0 <= i < 32) does not change anything (i being replaced by i).
Warining ! The new value to substitute shall belong to range [0,31] for red and blue and [0;63] for green.
Another example:: rise lighting by 100% for green compound:
new_val = i * 2 ;
if ( new_val > 63) new_val = 63 ; /* Important ! */
green[i] = new_val ; /* For 0 <= i < 64) */

Remarks | This function operates on Machine specific format ! You shall not call RaTCConvert or RaTCInvConvert.
VAPI Version | 1.03 or greater

Prototype | void cdecl RaTC32RemapColors(REMAP_COLORS *rc)
Parameters | [IN] rc : Pointer to a REMAP_COLORS structure defining elementary color changes, first pixel to change and number of pixels to operate on.
Return | None

Description

Change the current color spreading of a 32bit True Color image. red, green and blue fields of REMAP_COLORS shall point to arrays of 256 (256=2^8) elements each element being the value to substitute at this array index for instance the formula::
red[i] = i ; (0 <= i < 256) does not change anything (i being replaced by i).
Warining ! The new value to substitute shall belong to range [0,255].
Another example:: lower lighting by 20% for all compounds:
new_val = (80 * i) / 100 ;
/* Note that we still stay in [0;255] range ...*/
red[i] = green[i] = blue[i] = new_val ; /* For 0 <= i < 256) */

Remarks | This function operates on Machine specific format ! You shall not call RaTCConvert or RaTCInvConvert.
VAPI Version | 1.03 or greater

Prototype | void cdecl RaRasterRotateGetDstMFDB(MFDB *in, MFDB *out, long angle)
Parameters | [IN] in : MFDB describing image to be rotated [OUT]out : destination MFDB [IN] angle : Angle in degrees for the rotation
Return | None
Description | Used to know the the width/height after rotation in order to proper allocate the required memory. All fileds but fd_addr are set as the memory is NOT allocated.
Remarks | You should call this function right before the next one.
VAPI Version | 1.03 or greater

Prototype | long cdecl RaRasterRotate(MFDB *in, MFDB *out, long angle, long flags)
Parameters | [IN] in : MFDB describing image to be rotated [OUT]out : Destination MFDB [IN] angle : Angle in degrees for the rotation [IN] flags : if bit#0 is set, inform VAPI to display a progress window
Return | ELDV_NOERROR : life's good ELDV_NOTENOUGHMEMORY : crystal clear... ELDV_CANCELLED : (only possible if progress window is requested) ELDV_GENERALFAILURE : crystal clear...
Description | Perform the requested rotation. Destination MFDB should be allocated or this function will allocate it. Note that this last option is a bit dangerous as it is now up to the LDV to call RaRasterFree to free it. Good news is that VAPI uses standard VDI format if necessary.
Remarks | If angle is a multiple of 90degrees, specific routines will be called to avoid un-necessary sinus and cosinus computations
VAPI Version | 1.03 or greater

|  | VISION Documentation (VAPI) |  | Last update 08/04/18
| RASTER INTERFACE |