VDI IMAGE COPYING ------------------- By: M†rten Lindstr”m ----------------------- When writing the documentation for my image un/packing sub-routines (in assembler) designed to be used with the VDI copy functions, I realised/remembered that, to a newcomer to GEM, the VDI functions themselves need a bit of explanation too. This is a description not on HOW to pass parameters or call VDI functions, but on WHAT parameters to pass and functions to call and WHY. Screen dimensions and number of planes -------------------------------------- As with all (compatible) work on the screen you should never assume it is of a particular size or number of colour planes. So just as a quick reminder, you get the screen dimensions (coordinates of lower right corner) as the first two words of the WORK_OUT array returned when you open a (virtual) workstation (with V_OPNVWK). To get the number of planes you call VQ_EXTND after which the number can be found as WORK_OUT[4] (i.e. the word at offset 8 from WORK_OUT start.) The MFDB (Memory Form Definition Block) -------- As parameters, all the VDI copy functions use pointers NOT to the image/screen data but to MFDBs: MFDB (20 bytes): L: Pointer to image (or 0 = screen) W: Width in pixels W: Height W: Width in words = (width in pixels +15)/16 truncated W: Format flag: 1 for device independent 0 for device specific W: Number of planes 3W: 0 (reserved) An MFDB for the screen needs only to consist of a single zeroed longword. Picture formats --------------- The format flag describes how the image data are arranged: 0 - DEVICE SPECIFIC: This is how the screen memory is organized and depends on where the program happens to be running. For all standard ST resolutions it is "word interleaved" (if you don't understand this term don't worry about it), but in a general program, written to be 100% compatible, you cannot make any assumptions at all regarding the organization of a device specific image - including the screen. And therefore you should not manipulate it directly in any way. 1 - DEVICE INDEPENDENT: Here the image data are separated according to 'colour planes', i.e. first comes colour plane 0 for the complete image, then colour plane 1 for the full image etc. (Colour plane 0 contains bit 0 for all pixels, plane 1 contains bit 1 etc. Together these bits form a colour number for each pixel.) In each plane the pixel data come in the 'natural order', line-wise 'left to right' (bytes in address number order and more significant bits of byte before the lesser ones) beginning with the top line and ending with the bottom line. Each new pixel line always starts at next word boundary. An image in this format can safely be manipulated without 'dirtying' the code one bit. In practice you should load all images as device independent forms, then transform them to device specific format (with VR_TRNFM) after which you can copy (rectangles of) them to screen (with VRO_CPYFM/VRT_CPYFM). In the opposite direction you can copy from screen to a device specific form, which can then be transformed before it is exported as an image file. VR_TRNFM (Raster TRaNsForM) -------- This function transforms a device independent form to device specific format or vice versa. As parameters, it takes TWO pointers to source and destination MFDBs. These CAN be the same (to save space) but that makes the transformation very slow. VR_TRNFM will look at the format flag for the source MFDB only and invert this in the destination MFDB. NOTE that VR_TRNFM must be used on EVERY image you import (load as a file) before you can copy it to screen. Even mono images need to be transformed if you want your program to be 100% compatible (in spite of the fact that transformations for Atari standard mono resolutions perform nothing but a plain copy operation). VR_TRNFM does NOT (contrary to what is said in the Atari Compendium) transform colour numbers in any way. VRO_CPYFM (Raster Opaque CoPY ForM) --------- Copies a rectangle from a form to another. Both forms must (in present versions of TOS) be DEVICE SPECIFIC. And they both must contain the same number of planes. Since VR_TRNFM too demands forms with equal number of planes, the latter requirement means that if the actual number of image planes is less than the screen planes, then you must add extra memory space to (the end of) the device independent image as fill planes, before transformation is effected. In the opposite case (# screen planes less than # image planes) you only have to change the number of planes in the MFDB (which will make VR_TRNFM ignore the extra planes). Parameters of VRO_CPYFM: Copy mode: word = 3 for plain copy Pointer to rectangle definition Pointer to source MFDB Pointer to destination MFDB If you use other values than 3 for copy mode, you can logically combine source and destination images in various ways. Of the 16 possible - more or less peculiar - modes, 1 ANDs and 7 ORs source with destination (possibly usable for sprite copying). The rectangle definition is an array of 8 words: Source X1,Y1, X2,Y2, Destination X1,Y1, X2,Y2 where X1,Y2 are the coordinates for the upper left and X2,Y2 the lower right corner of the rectangle. Obviously you should make sure that the width and height are the same for source and destination rectangles. The present versions of VDI uses only the source size I think, but a future version could implement scaling. If you are unfamiliar to VDI you should note that the difference between first and second X/Y of each rectangle is ONE LESS than the width/height of the rectangle. For example a rectangle covering a complete ST low rez screen would be defined as 0,0,319,199 (but again you should use screen dimensions got from WORK_OUT - see above.) VRT_CPYFM (Raster Transparent CoPY ForM) --------- This function works as VRO_CPYFM except that the source form should be single plane (regardless of number of planes in destination). For one-plane (i.e. mono) images, VRT_CPYFM can thus be used as an alternative to VRO_CPYFM, with the advantage that no fill planes have to be added before transformation (saving memory). The disadvantage seems to be (without blitter at least) a somewhat slower speed of operation. A difference that should be noted is that the copy mode word is defined differently for VRO_CPYFM and VRT_CPYFM. While the former uses its own 16 modes, VRT_CPYFM uses the standard four VDI write modes. This means that for plain copy you should use 3 with VRO_CPYFM but 1 with VRT_CPYFM. As a special further parameter with VRT_CPYFM are added VDI colour numbers for the ones and zeros of the image data. Parameters of VRT_CPYFM: Write mode: word = 1 for plain copy NOTE!!! Pointer to rectangle definition Pointer to source MFDB Pointer to destination MFDB (Pointer to) VDI colour numbers for ones and zeros. Colour numbers -------------- As is well known the (Atari) VDI uses its own mixed-up colour numbers. These numbers should never be used as indexes to the colours of an image file palette (which are ordered according the numbers formed - for each pixel - by the colour plane bits). Instead you should create a translation table: bitplane numbers -> VDI numbers. For this the function V_GET_PIXEL can be used - See the file IMG_IFF for a further discussion.