Home / Autodocs / graphics.library
NAME
- ReadPixelArray8
-
Read 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)
SYNOPSIS
count = ReadPixelArray8(rp,xstart,ystart,xstop,ystop,array,temprp)
D0 A0 D0:16 D1:16 D2:16 D3:16 A2 A1
LONG ReadPixelArray8(struct RastPort *, UWORD, UWORD, UWORD, UWORD,
D0 A0 D0:16 D1:16 D2:16 D3:16 A2 A1
LONG ReadPixelArray8(struct RastPort *, UWORD, UWORD, UWORD, UWORD,
UBYTE *, struct RastPort *);
FUNCTION
Read pixel color data from the RastPort, beginning at position (xstart, ystart), stopping at position (xstop, ystart). This process will continue for each following row, reading from position xstart to xstop, until the ystop row has been read.
When finished, a total of (xstop - xstart + 1) * (ystop - ystart + 1) pixels will have been read in sequence.
The color data is read in bulk, which is significantly faster than calling ReadPixel() for each single pixel covered.
When finished, a total of (xstop - xstart + 1) * (ystop - ystart + 1) pixels will have been read in sequence.
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
- 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 into which to store 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.
- 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; this will be (xstop - xstart + 1) * (ystop - ystart + 1)
WARNING
READPIXELARRAY8 MAY STORE MORE DATA THAN YOU ASKED FOR
ReadPixelArray8() works like the ReadPixelLine8() function, reading one row at a time. As such it has the same limitations as ReadPixelLine8() in that each row read will copy (xstop - xstart + 1) 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 (xstop - xstart + 1), rounded up to a multiple of 16.
If you ask for n = (xstop - xstart + 1) pixels to be read, data for 16 * ((n + 15) / 16) pixels will be read and stored in each row of the array. Even with xstop == xstart a total of 16 pixels will be read and their data will be stored in the row of the array.
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.
READPIXELARRAY8 DOES NOT RETURN THE TOTAL NUMBER OF PIXELS READ
Every call to ReadPixelArray8() returns the number of pixels you requested to be read. In practice, ReadPixelArray8() 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.
ReadPixelArray8() works like the ReadPixelLine8() function, reading one row at a time. As such it has the same limitations as ReadPixelLine8() in that each row read will copy (xstop - xstart + 1) 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 (xstop - xstart + 1), rounded up to a multiple of 16.
If you ask for n = (xstop - xstart + 1) pixels to be read, data for 16 * ((n + 15) / 16) pixels will be read and stored in each row of the array. Even with xstop == xstart a total of 16 pixels will be read and their data will be stored in the row of the array.
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.
READPIXELARRAY8 DOES NOT RETURN THE TOTAL NUMBER OF PIXELS READ
Every call to ReadPixelArray8() returns the number of pixels you requested to be read. In practice, ReadPixelArray8() 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 ReadPixelArray8() 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 EXAMPLE section.
For ReadPixelArray8() 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 EXAMPLE section.
For ReadPixelArray8() 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, xstop - xstart + 1))
{
}
#include <proto/graphics.h>
struct RastPort temprp;
UBYTE * array;
if (setup_temp_rastport(&temprp, rp, xstop - xstart + 1))
{
array = allocate_pixel_array(xstop - xstart + 1, ystop - ystart + 1);
if (array != NULL)
{
}
cleanup_temp_rastport(&temprp, xstop - xstart + 1);
if (array != NULL)
{
/* Call ReadPixelArray8(rp,xstart,ystart,xstop,ystop,array,&temprp)
FreeVec(array);
* as needed.
*/
*/
cleanup_temp_rastport(&temprp, xstop - xstart + 1);
EXAMPLE
To initialize a temporary RastPort and allocate memory for its BitMap
you could use the following functions. Both require a temporary RastPort
which first has to be initialized by setup_temp_rastport(). This involves
allocating memory for a BitMap. In order to release the allocated memory
call cleanup_temp_rastport().
The temporary RastPort can be allocated separately but a declaring a
local 'struct RastPort temprp;' is fine, too.
The ReadPixelLine8(), ReadPixelArray8(), WritePixelLine8() and
WritePixelArray8() functions transfer pixel color data to/from a
memory buffer with very specific size requirements. The
allocate_pixel_array() function below will accomplish this.
/* Initialize the temporary RastPort, then create a BitMap
BOOL
setup_temp_rastport(
{
}
/* Release the BitMap allocated for the temporary RastPort
VOID
cleanup_temp_rastport(
{
}
/* Allocate a memory buffer suitable for use with the ReadPixelLine8(),
UBYTE *
allocate_pixel_array(UWORD width, UWORD height)
{
}
you could use the following functions. Both require a temporary RastPort
which first has to be initialized by setup_temp_rastport(). This involves
allocating memory for a BitMap. In order to release the allocated memory
call cleanup_temp_rastport().
The temporary RastPort can be allocated separately but a declaring a
local 'struct RastPort temprp;' is fine, too.
The ReadPixelLine8(), ReadPixelArray8(), WritePixelLine8() and
WritePixelArray8() functions transfer pixel color data to/from a
memory buffer with very specific size requirements. The
allocate_pixel_array() function below will accomplish this.
/* Initialize the temporary RastPort, then create a BitMap
* which is suitable for use with ReadPixelLine8(), ReadPixelArray8(),
* WritePixelLine8() and WritePixelArray8().
*
* This function will return FALSE if the BitMap could not be
* created and TRUE otherwise.
*
* Call cleanup_temp_rastport() when the BitMap is no longer needed,
* so that the memory allocated for it will be released again.
*/
* WritePixelLine8() and WritePixelArray8().
*
* This function will return FALSE if the BitMap could not be
* created and TRUE otherwise.
*
* Call cleanup_temp_rastport() when the BitMap is no longer needed,
* so that the memory allocated for it will be released again.
*/
setup_temp_rastport(
struct RastPort * temp_rp,
CONST struct RastPort * rp,
UWORD width)
CONST struct RastPort * rp,
UWORD width)
struct BitMap * temp_rp_bm;
BOOL success = FALSE;
int i, j;
/* Use a default RastPort configuration to avoid side-effects
InitRastPort(temp_rp);
/* For Kickstart 3.0 and beyond use the designated BitMap
if (GfxBase->LibNode.lib_Version >= 39)
{
}
/* For Kickstart 2.x set up a BitMap via InitBitMap() and
else
{
}
success = (BOOL)(temp_rp->BitMap != NULL);
return success;
BOOL success = FALSE;
int i, j;
/* Use a default RastPort configuration to avoid side-effects
* resulting from copying the source RastPort data.
*/
*/
/* For Kickstart 3.0 and beyond use the designated BitMap
* allocation function in graphics.library.
*/
*/
{
temp_rp->BitMap = AllocBitMap(width, 1,
GetBitMapAttr(rp->BitMap, BMA_DEPTH),
GetBitMapAttr(rp->BitMap, BMA_FLAGS) & BMF_INTERLEAVED,
NULL);
GetBitMapAttr(rp->BitMap, BMA_FLAGS) & BMF_INTERLEAVED,
NULL);
/* For Kickstart 2.x set up a BitMap via InitBitMap() and
{
temp_rp_bm = AllocVec(sizeof(*temp_rp_bm), MEMF_PUBLIC);
if (temp_rp_bm != NULL)
{
}
if (temp_rp_bm != NULL)
{
InitBitMap(temp_rp_bm, width, 1, rp->BitMap->Depth);
temp_rp->BitMap = temp_rp_bm;
for (i = 0 ; i < temp_rp_bm->Depth ; i++)
{
}
temp_rp->BitMap = temp_rp_bm;
for (i = 0 ; i < temp_rp_bm->Depth ; i++)
{
temp_rp_bm->Planes[i] = AllocRaster(width, 1);
if (temp_rp_bm->Planes[i] == NULL)
{
}
if (temp_rp_bm->Planes[i] == NULL)
{
/* Free all the bit planes allocated so far. */
for (j = 0 ; j < i ; j++)
{
}
temp_rp->BitMap = NULL;
FreeVec(temp_rp_bm);
break;
for (j = 0 ; j < i ; j++)
{
temp_rp->BitMap = NULL;
FreeVec(temp_rp_bm);
break;
success = (BOOL)(temp_rp->BitMap != NULL);
return success;
/* Release the BitMap allocated for the temporary RastPort
* when no longer needed.
*/
*/
cleanup_temp_rastport(
struct RastPort * temp_rp,
UWORD width)
UWORD width)
int i;
if (temp_rp->BitMap != NULL)
{
}
if (temp_rp->BitMap != NULL)
{
/* Wait for the Blitter to finish, in case it is still
WaitBlit();
if (GfxBase->LibNode.lib_Version >= 39)
{
}
else
{
}
temp_rp->BitMap = NULL;
* modifying the BitMap created.
*/
*/
if (GfxBase->LibNode.lib_Version >= 39)
{
FreeBitMap(temp_rp->BitMap);
else
{
for (i = 0 ; i < temp_rp->BitMap->Depth ; i++)
{
}
{
temp_rp->BitMap = NULL;
/* Allocate a memory buffer suitable for use with the ReadPixelLine8(),
* ReadPixelArray8(), WritePixelLine8() and WritePixelArray8() functions.
*
* Returns the address of the buffer allocated or NULL for failure. The
* memory buffer allocated can be freed with the FreeVec() function.
*
* For ReadPixelLine8() and WritePixelLine8() you would use height = 1.
*/
*
* Returns the address of the buffer allocated or NULL for failure. The
* memory buffer allocated can be freed with the FreeVec() function.
*
* For ReadPixelLine8() and WritePixelLine8() you would use height = 1.
*/
allocate_pixel_array(UWORD width, UWORD height)
{
UBYTE * array;
array = AllocVec(RASSIZE(width, height), MEMF_PUBLIC);
return array;
array = AllocVec(RASSIZE(width, height), MEMF_PUBLIC);
return array;
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.