WritePixelArray8

Write the color values of all the pixels in a rectangular array whose top left and bottom right edges describe its position, width and height. (V36)

Write pixel color data to the RastPort, beginning at position (xstart, ystart), stopping at position (xstop, ystart). This process will continue for each following row, writing from position xstart to xstop, until the ystop row has been written.

When finished, a total of (xstop - xstart + 1) * (ystop - ystart + 1) pixels will have been written in sequence.

The color data is written in bulk, which is significantly faster than calling WritePixel() for each single pixel covered.

rp

pointer to a RastPort structure

xstart

see next

ystart

starting point in the RastPort; xstart must be <= xstop

xstop

see next

ystop

stopping point in the RastPort; ystart must be <= ystop

array

Pointer to an array of UBYTEs from which to fetch the pixel data; the array must be large enough to hold a total of RASSIZE(xstop - xstart + 1, ystop - ystart + 1) number of bytes See the NOTES section for setting up the array.

CAUTION:

The contents of the array will be destroyed. See the WARNING section for more information.

temprp

Temporary RastPort See the NOTES section for setting up the temporary RastPort.

The number of pixels written, which will be (xstop - xstart + 1) * (ystop - ystart + 1)

WRITEPIXELARRAY8 WILL DESTROY THE CONTENTS OF THE ARRAY

The conversion process which turns pixel color data into bit plane data has a side-effect. The array is used as "scratch", performing the conversion in place. This means that you cannot use a single pixel array both for storing and rendering pixel data if you want to retain its contents. When the conversion is finished, the contents of the array will be completely replaced.

While 3rd party patches and retargetable graphics (RTG) systems may avoid destroying the contents of the array, you should always assume that it will be destroyed. There is no safe and reliable way to determine in advance whether the array contents will be preserved.

WRITEPIXELARRAY8 WILL DESTROY MORE DATA THAN YOU WANTED TO WRITE

WritePixelArray8() works like the WritePixelLine8() function, processing one row at a time. As such it has the same limitations as WritePixelLine8() in that each row fetched will convert the pixel color data, copy it to the temprp.BitMap and then use ClipBlit() to copy xstop - xstart + 1 number of pixels to the destination RastPort.

The conversion from pixels to bit plane data does not merely affect (xstop - xstart + 1) bytes per row. Effectively, the number of pixels converted matches the horizontal size of the temprp.BitMap. The number of bytes will be (xstop - xstart + 1), rounded up to a multiple of 16.

If you ask for n = (xstop - xstart + 1) pixels to be written per row, data for 16 * ((n + 15) / 16) pixels will be converted in the array. Even with xstop == xstart a total of 16 pixels will be converted.

This means that the array you need to allocate will not necessarily feature (xstop - xstart + 1) bytes per row. There may be padding of of up to 15 bytes at the end of each single row. To calculate the complete size of each row, the RASSIZE() macro found in <graphics/gfx.h> may be used. The row size in bytes can be calculated as RASSIZE(xstop - xstart + 1, 1).

The easiest way to ensure that the array is large enough is to make use of the RASSIZE() macro. Make sure that your array has room for at least RASSIZE(xstop - xstart + 1, ystop - ystart + 1) number of bytes.

The correct use of WritePixelArray8() requires the temporary RastPort and the array to read the pixel color data from to be set up in a very specific manner. Deviating from these requirements can lead to data corruption and undefined behavior.

How you would set up the temporary RastPort and allocate a memory buffer of the proper size is detailed with ready to use example code in the EXAMPLE section.

For WritePixelArray8() you would use the example code as follows:

Previous versions of this function could read over the end of the supplied array, or even write into it. Even though the code attempted to restore the original data, it might have been too late in case program code (e.g. interrupt code) was contained in the memory region past the buffer end.

Previous documentation suggested copying the contents of the rp parameter when setting up the temprp (temporary RastPort). This is not recommended because the rp.Mask settings could interfere with the ClipBlit() operation implied by WritePixelLine8(). This could yield corrupted color data.

V45 and above no longer require the temporary RastPort address in register A1. You no longer need to initialize a temporary RastPort and may pass NULL in place of its address instead.

WritePixel(), ReadPixelArray8(), WritePixelLine8(), WriteChunkyPixels(), ClipBlit(), <graphics/gfx.h>, <graphics/rastport.h>