WritePixelLine8

Write the color values of all the pixels on a horizontal line, starting at a specified x,y location and continuing right for a given number of pixels. (V36)

Write pixel color data to the RastPort, beginning at position (xstart, ystart) and stopping at position (xstart + pixel_count - 1, ystart).

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

rp

Pointer to a RastPort structure

x

see next

y

A point in the RastPort

pixel_count

Count of horizontal pixels to change; this must be >= 0

array

Pointer to an array of UBYTEs from which to fetch the pixel data; the array must be large enough to hold RASSIZE(num_pixels, 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 (identical to pixel_count)

WRITEPIXELLINE8 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.

WRITEPIXELLINE8 WILL DESTROY MORE DATA THAN YOU WANTED TO WRITE

WritePixelLine8() will convert the contents of the array into bit plane data, copy the data to the BitMap of the temporary RastPort and use ClipBlit() to transfer pixel_count number of pixels to the destination RastPort.

The conversion from pixels to bit plane data does not merely affect num_pixels bytes per row. Effectively, the number of pixels converted matches the horizontal size of the temprp.BitMap. The number of bytes will be pixel_count, rounded up to a multiple of 16.

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

The easiest way to ensure that the array is large enough is to make use of the RASSIZE() macro found in <graphics/gfx.h>. Make sure that your array has room for at least RASSIZE(pixel_count, 1) number of bytes.

The correct use of WritePixelLine8() 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 ReadPixelArray8() documentation EXAMPLE section.

For WritePixelLine8() 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(), WritePixelArray8(), WriteChunkyPixels(), ClipBlit(), <graphics/gfx.h>, <graphics/rastport.h>