Enhanced NVDI 2.50 Functions ============================ This document describes the enhanced NVDI 2.50 functions for screen output. 1. Off-Screen Bitmaps ===================== Sometimes it's very useful to perform drawing operations on hidden screens and to use vro_cpyfm() to transfer the complete image to the screen - you may want to avoid screen flickering or just cache a screen region, etc.. These hidden screens are called `Off-Screen Bitmaps'. You can create off-screen bitmaps by calling OPEN BITMAP. You can either pass the size of a bitmap to v_opnbm() which will allocate memory for it, or you can pass a pointer to a bitmap you have already allocated memory for. The bitmap will be in device-specific or monochrome format. Therefore you can copy raster areas from screen to a bitmap and vice versa without using vr_trnfm(). The function CLOSE BITMAP closes a bitmap created with OPEN BITMAP and - if necessary - frees the memory block. OPEN BITMAP (VDI 100, 1) void v_opnbm( WORD *work_in, MFDB *bitmap, WORD *handle, WORD *work_out ) { pb[1] = work_in; pb[3] = work_out; pb[4] = work_out + 45; contrl[0] = 100; contrl[1] = 0; contrl[3] = 20; contrl[5] = 1; *(MFDB *)&contrl[7] = bitmap; vdi(); *handle = contrl[6]; pb[1] = intin; pb[3] = intout; pb[4] = ptsout; } VDI arrays: Element | Content ------------------|------------------------------------------- contrl[0] | 100 opcode for v_opnbm() contrl[1] | 0 number of parameters in ptsin contrl[2] | 6 number of parameters in ptsout contrl[3] | 20 number of parameters in intin contrl[4] | 45 number of parameters in intout contrl[5] | 1 sub-opcode for v_opnbm() contrl[6] | handle contrl[7..8] | bitmap pointer to the MFDB of bitmap | intin[0..19] | work_in[0..19] | intout[0..44] | work_out[0..44] | ptsout[0..11] | work_out[45..56] handle: graf_handle() work_in[0..10]: see v_opnwk()/v_opnvwk() work_in[0]: Getrez() + 2 work_in[11]: Width -1 (e.g. 1279) work_in[12]: Height -1 (e.g. 959) work_in[13]: Width of a pixel in 1/1000 mm work_in[14]: Height of a pixel in 1/1000 mm work_in[15..19]: reserved, should contain 0 Attention: Work_in[11] + 1 should be divisible by 16 without remainder. Otherwise the VDI driver will round up (work_in[11] + 1) to the next number which can be divided by 16 without remainder. If pixel width and height are 0 the pixel size of the screen workstation is used. work_out[0..1]: see v_opnwk()/v_opnvwk() work_out[2]: 0 work_out[3..38]: see v_opnwk()/v_opnvwk() work_out[39] 0 (no hardware clut) work_out[39..56]: see v_opnwk()/v_opnvwk() bitmap: pointer to MFDB If bitmap->fd_addr is zero, the VDI will allocate memory for the bitmap and will clear it (in contrast to v_opnvwk() ). To open a bitmap in device-specific format bitmap->fd_nplanes should be zero or the number of planes of the screen (work_out[4] from vq_extnd()). If bitmap->fd_nplanes is 1, a monochrome bitmap will be created. The elements of the MFDB (fd_addr, fd_w, fd_h, fd_wdwidth, fd_stand,fd_nplanes) are set by the VDI before returning from v_opnbm(). If there is not enough memory to create a bitmap the handle will be zero and the MFDB will not be changed. If bitmap->fd_addr is not zero, it will be used as pointer to a bitmap. If the bitmap is in standard format, it will be transformed into device-specific format. If the number of planes of the bitmap is not supported by the VDI, a zero handle will be returned. CLOSE BITMAP (VDI 101, 1) void v_clsbm( WORD handle ) { contrl[0] = 101; contrl[1] = 0; contrl[3] = 0; contrl[5] = 1; contrl[6] = handle; vdi(); } VDI arrays: Element | Content ------------------|------------------------------------------- contrl[0] | 101 opcode for v_clsbm() contrl[1] | 0 number of parameter in ptsin contrl[2] | 0 number of parameter in ptsout contrl[3] | 0 number of parameter in intin contrl[4] | 0 number of parameter in intout contrl[5] | 1 sub-opcode for v_clsbm() contrl[6] | handle The function v_clsbm() closes the bitmap specified with handle. The memory of the bitmap will be freed if the VDI has allocated it. Raster Operations and Off-Screen Bitmaps: ========================================= Raster operations between screen and a bitmap generally have to be done in device-specific format. If a bitmap is the destination of a raster operation, you should use the bitmap's handle. Otherwise vro_cpyfm() or vrt_cpyfm() cannot clip the area they have to copy and may overwrite other applications' memory. If you use the handle of a bitmap created by v_opnbm() for a raster operation then a zero in MFDB->fd_addr is not a pointer to the screen but to the bitmap. In contrast to a screen workstation on a bitmap clipping is also done when MFDB->fd_addr is the address of the bitmap returned by v_opnbm() (on a screen workstation clipping is only done when MFDB->fd_addr is zero). See also: BITMAP.C ESCAPES ------- VDI escape functions can't be used on Off-Screen bitmaps. The calls are ignored. vs_color()/vq_color() --------------------- vs_color() and vq_color() can be used in Hi- or True Color mode on a Off-Screen bitmap. Otherwise the calls are ignored (vq_color() returns -1 if not used in Hi- or True Color mode). vst_point() ----------- vst_point() and all other functions that change the text character height in printer points won't set the requested character size if the pixel height and width of the screen is different to the pixel height and width of the Off-Screen bitmap. v_show_c()/v_hide_c() --------------------- v_show_c() and v_hide_c() can't be used on Off-Screen bitmaps. The calls are ignored. 2. vq_scrninfo() ================ The funcion INQUIRE SCREEN INFORMATION returns additional information about the device-specific screen format. This function is useful for programs which - support Genlock (Overlay) - build rasters (also in TrueColor) and want to copy them with vro_cpyfm() to the screen - save rasters (e.g. XIMGs) VQ_SCRNINFO( 102, 1 ) void vq_scrninfo( WORD handle, WORD *work_out ) { pb[3] = work_out; intin[0] = 2; contrl[0] = 102; contrl[1] = 0; contrl[3] = 1; contrl[5] = 1; contrl[6] = handle; vdi(); pb[3] = intout; } VDI arrays: Element | Content ------------------|------------------------------------------- contrl[0] | 102 opcode for vq_scrninfo() contrl[1] | 0 number of parameters in ptsin contrl[2] | 0 number of parameters in ptsout contrl[3] | 1 number of parameters in intin contrl[4] | 272 number of parameters in intout contrl[5] | 1 sub-opcode for vq_scrninfo() contrl[6] | handle | intin[0] | 2 return additional information | intout[0..272] | work_out[0..272] intout[0]: Device Format 0: interleaved planes, word-wide (ATARI graphic) 1: whole planes (standard format) 2: packed pixels -1: unknown format intout[1]: Supported CLUT: 0: no CLUT (e.g. TTM 194) 1: hardware CLUT 2: software CLUT (HiColor or TrueColor) intout[2]: number of planes (bits) per pixel intout[3/4]:number of colors or 0L (more than 2*10^31 colors) intout[8]: number of bits for red intensity intout[9]: number of bits for green intensity intout[10]: number of bits for blue intensity intout[11]: number of bits for alpha channel intout[12]: number of bits for genlock intout[13]: number of unused bits If a CLUT exists: intout[16-271]: pixel value of the corresponding VDI color index HiColor or TrueColor: intout[16..31]: association of bit number in the pixel and bit of the red intensity intout[32..47]: association of bit number in the pixel and bit of the green intensity intout[48..63]: association of bit number in the pixel and bit of the blue intensity intout[64..79]: association of bit number for alpha channel intout[80..95]: association of bit numbers for genlock intout[96..127]: bit numbers of unused bits intout[128..271]: reserved (0) Examples: --------- The following output would be done in 256 colors on the Falcon: intout | Value | Meaning ---------|--------|----------------------------------------------------- 0 | 0 | interleaved planes 1 | 1 | hardware CLUT exists 2 | 8 | 8 bit per pixel 3/4 | 256 | 256 colors 8 | 6 | 6 bits for red intensity 9 | 6 | 6 bits for green intensity 10 | 6 | 6 bits for blue intensity 11 | 0 | no bit for alpha channel 12 | 0 | no bit for genlock 13 | 0 | no unused bits | | | | 16 | 0 | pixel value of VDI color index 0 17 | 255 | pixel value of VDI color index 1 18 | 2 | pixel value of VDI color index 2 ... | ... | 271 | 15 | pixel value of VDI color index 255 The following output would be done in HiColor on the Falcon: intout | Value | Meaning ---------|--------|----------------------------------------------------- 0 | 2 | packed pixels 1 | 2 | HiColor/TrueColor 2 | 16 | 16 bit per pixel 3/4 | 32768 | 32768 colors 8 | 5 | 5 bits for red intensity 9 | 5 | 5 bits for green intensity 10 | 5 | 5 bits for blue intensity 11 | 0 | no bit for alpha channel 12 | 1 | 1 bit for genlock 13 | 0 | no unused bits | | | | 16 | 11 | bit 0 of the red intensity (least significant bit) | | is in bit 11 of the pixel 17 | 12 | bit 1 is in bit 12 of the pixel 18 | 13 | ... 19 | 14 | ... 20 | 15 | bit 4 of the red intensity (most significant bit) | | is in bit 15 of the pixel 21..31 | -1 | bits are not used for red intensity | | | | 32 | 6 | bit 0 of the green intensity (least significant bit) | | is in bit 6 of the pixel 33 | 7 | bit 1 is in bit 7 of the pixel 34 | 8 | ... 35 | 9 | ... 36 | 10 | bit 4 of the green intensity (most significant bit) | | is in bit 10 of the pixel 37..37 | -1 | bits are not used for green intensity | | | | 48 | 0 | bit 0 of the blue intensity (least significant bit) | | is in bit 0 of the pixel 49 | 1 | bit 1 is in bit 1 of the pixel 50 | 2 | ... 51 | 3 | ... 52 | 4 | bit 4 of the blue intensity (most significant bit) | | is in bit 4 of the pixel 53..63 | -1 | bits are not used for blue intensity | | | | 64..79 | -1 | no alpha channel | | | | 80 | 5 | bit for genlock 81..95 | -1 | not used for genlock | | | | 96..127| -1 | no unused bits | | | | 3. Recognizing the enhanced VDI functions ========================================= NVDI (and also the ENHANCER for the ATARI-VDI) will place a 'EdDI' cookie in the cookie jar containing a dispatcher adress in the cookie value. The dispatcher uses Turbo C/Pure C calling conventions (register d0 contains the opcode; registers d1-d2/a0-a1 and the stack may be used for additional parameters). Till now only opcode 0 is implemented. This opcode returns the 'EdDI' version number. Version 1.00 (retun value is $100) supports v_opnbm(), v_clsbm() and vq_scrninfo().