Home / Autodocs / graphics.library
NAME
- ReadPixelLine8
-
Read 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)
SYNOPSIS
count = ReadPixelLine8(rp,xstart,ystart,pixel_count,array,temprp)
D0 A0 D0:16 D1:16 D2 A2 A1
LONG ReadPixelLine8(struct RastPort *, UWORD, UWORD, UWORD,
D0 A0 D0:16 D1:16 D2 A2 A1
LONG ReadPixelLine8(struct RastPort *, UWORD, UWORD, UWORD,
UBYTE *, struct RastPort * );
FUNCTION
Read pixel color data from the RastPort, beginning at position (xstart, ystart) and stopping at position (xstart + pixel_count - 1, ystart).
The color data is read in bulk, which is significantly faster than calling ReadPixel() for each single pixel covered.
The color data is read in bulk, which is significantly faster than calling ReadPixel() for each single pixel covered.
INPUTS
- rp
-
Pointer to a RastPort structure
- x
-
see next
- y
-
A point in the RastPort
- pixel_count
-
Count of horizontal pixels to read; this must be >= 0
- array
-
Pointer to an array of UBYTEs into which to store 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.
- temprp
-
Temporary RastPort See the NOTES section for setting up the temporary RastPort.
RESULT
For each pixel in the array:
- Pen
-
Pixel color (0..255) at that position
- count
-
The number of pixels read (identical to pixel_count)
WARNING
READPIXELLINE8 MAY STORE MORE DATA THAN YOU ASKED FOR
ReadPixelLine8() will copy pixel_count number of pixels to the temporary RastPort by means of ClipBlit() and then process the entire row. This means that the number of bytes written to the array will be rounded up to match 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 read, data for 16 * ((n + 15) / 16) pixels will be read and stored in the array. Even with pixel_count == 1 a total of 16 pixels will be read and their data will be stored in the array.
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.
READPIXELLINE8 DOES NOT RETURN THE TOTAL NUMBER OF PIXELS READ
Every call to ReadPixelLine8() returns the number of pixels you requested to be read. In practice, ReadPixelLine8() may read and process more than these pixels. Do not expect the pixel count returned to accurately reflect the number of bytes changed in the array.
ReadPixelLine8() will copy pixel_count number of pixels to the temporary RastPort by means of ClipBlit() and then process the entire row. This means that the number of bytes written to the array will be rounded up to match 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 read, data for 16 * ((n + 15) / 16) pixels will be read and stored in the array. Even with pixel_count == 1 a total of 16 pixels will be read and their data will be stored in the array.
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.
READPIXELLINE8 DOES NOT RETURN THE TOTAL NUMBER OF PIXELS READ
Every call to ReadPixelLine8() returns the number of pixels you requested to be read. In practice, ReadPixelLine8() may read and process more than these pixels. Do not expect the pixel count returned to accurately reflect the number of bytes changed in the array.
NOTES
The correct use of ReadPixelLine8() requires the temporary RastPort and the array to store the pixel color data in 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 ReadPixelLine8() you would use the example code as follows:
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 ReadPixelLine8() you would use the example code as follows:
#include <proto/exec.h>
#include <proto/graphics.h>
struct RastPort temprp;
UBYTE * array;
if (setup_temp_rastport(&temprp, rp, pixel_count))
{
}
#include <proto/graphics.h>
struct RastPort temprp;
UBYTE * array;
if (setup_temp_rastport(&temprp, rp, pixel_count))
{
array = allocate_pixel_array(pixel_count, 1);
if (array != NULL)
{
}
cleanup_temp_rastport(&temprp, pixel_count);
if (array != NULL)
{
/* Call ReadPixelLine8(rp,xstart,ystart,pixel_count,array,&temprp)
FreeVec(array);
* as needed.
*/
*/
cleanup_temp_rastport(&temprp, pixel_count);
BUGS
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 ReadPixelLine8(). This could yield corrupted color data.