Home / Autodocs / graphics.library
NAME
- WriteChunkyPixels
-
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. (V40)
SYNOPSIS
WriteChunkyPixels(rp,xstart,ystart,xstop,ystop,array,bytesperrow)
VOID WriteChunkyPixels(struct RastPort *, LONG, LONG,
A0 D0 D1 D2 D3 A2 D4
LONG, LONG, CONST UBYTE *, LONG);
FUNCTION
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.
The color data is written in bulk, which is significantly faster than calling WritePixel() for each single pixel covered.
The color data is written in bulk, which is significantly faster than calling WritePixel() 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 from which to fetch the pixel data. This data will not be changed.
- bytesperrow
-
The number of bytes per row in the source array. This should be at least as large as the number of pixels being written per line.
NOTES
BACKGROUND
The WriteChunkyPixels() function was introduced as part of Kickstart 3.1, which saw first use on the Amiga CD32 game console, released in late 1993.
The performance constraints, side-effects and complex setup needed to make use of WritePixelArray8() called for a faster and simpler function: WriteChunkyPixels(). On the Amiga CD32 dedicated conversion hardware would perform the transformation of the pixel data into bit plane data without destroying the pixel data in the process.
CONSTRAINTS AND DRAWBACKS
Prior to the changes in graphics.library V45 the WriteChunkyPixels() function was "emulated" by the Kickstart ROMs of all Amiga computers except for the Amiga CD32.
The emulation fell back onto using the WritePixelLine8() function, allocating temporary memory to perform a non-destructive conversion of the pixel data into bit plane data. While this conversion process achieved the desired outcome it suffered from serious performance problems.
Performance was markedly worse than for an equivalent use of WritePixelArray8(), not just because the temporary conversion buffer had to be allocated every time WritePixelArray8() was called. The emulation also had to initialize a temporary RastPort and allocate memory for a temporary BitMap. It also had to free the temporary BitMap, eventually.
Failure to allocate the temporary BitMap would result in the emulated conversion failing silently, leaving the destination RastPort unchanged.
WHEN IS WRITECHUNKYPIXELS() PREFERABLE TO WRITEPIXELARRAY8()?
If your target system is an Amiga CD32 then WriteChunkyPixels() is always the better choice.
For all other Amiga computers you should choose WriteChunkyPixels() only if the graphics.library version is >= 45.
For Amiga computers with graphics.library versions < 45 you should use WritePixelArray8(), observing its requirements and the preparations necessary to account for it side-effects.
CHUNKY-TO-PLANAR CONVERSION HARDWARE (V40-V44)
GfxBase->ChunkyToPlanarPtr is either NULL, or a pointer to a hardware register used to aid in the process of converting 8-bit chunky pixel data into the bit-plane format used by the Amiga custom display chips. If NULL, then such hardware is not present.
If an expansion device provides hardware which operates compatibly, than it can install the hardware address into this pointer at boot time, and the system will use it.
This pointer may be used for direct access to the chunky-to-planar conversion hardware, if more is desired than the straight chunky-pixel copy that is performed by WriteChunkyPixels().
If using the hardware directly, it should only be accessed when the task using it has control of the blitter (via OwnBlitter()), since this is the locking used to arbitrate usage of this device.
The hardware may be viewed as a device which accepts 32 8-bit chunky pixels and outputs 8 longwords of bitplane data.
For proper operation, exactly 8 longwords (containing 32 pixels) of chunky data should be written to *(GfxBase->ChunkyToPlanarPtr). After the data is written, bitplane data (starting with plane 0) can be read back a longword at a time. There is no need to read back all 8 longwords if the high-order bitplanes are not needed.
Since WriteChunkyPixels() is not particularly fast on systems without the chunky-to-planar hardware, time critical applications (games, etc) may want to use their own custom conversion routine if GfxBase->ChunkyToPlanarPtr is NULL, and call WriteChunkyPixels() otherwise.
This pointer is only present in GfxBase in versions of graphics.library >= 40, so this should be checked before the pointer is read.
The WriteChunkyPixels() function was introduced as part of Kickstart 3.1, which saw first use on the Amiga CD32 game console, released in late 1993.
The performance constraints, side-effects and complex setup needed to make use of WritePixelArray8() called for a faster and simpler function: WriteChunkyPixels(). On the Amiga CD32 dedicated conversion hardware would perform the transformation of the pixel data into bit plane data without destroying the pixel data in the process.
CONSTRAINTS AND DRAWBACKS
Prior to the changes in graphics.library V45 the WriteChunkyPixels() function was "emulated" by the Kickstart ROMs of all Amiga computers except for the Amiga CD32.
The emulation fell back onto using the WritePixelLine8() function, allocating temporary memory to perform a non-destructive conversion of the pixel data into bit plane data. While this conversion process achieved the desired outcome it suffered from serious performance problems.
Performance was markedly worse than for an equivalent use of WritePixelArray8(), not just because the temporary conversion buffer had to be allocated every time WritePixelArray8() was called. The emulation also had to initialize a temporary RastPort and allocate memory for a temporary BitMap. It also had to free the temporary BitMap, eventually.
Failure to allocate the temporary BitMap would result in the emulated conversion failing silently, leaving the destination RastPort unchanged.
WHEN IS WRITECHUNKYPIXELS() PREFERABLE TO WRITEPIXELARRAY8()?
If your target system is an Amiga CD32 then WriteChunkyPixels() is always the better choice.
For all other Amiga computers you should choose WriteChunkyPixels() only if the graphics.library version is >= 45.
For Amiga computers with graphics.library versions < 45 you should use WritePixelArray8(), observing its requirements and the preparations necessary to account for it side-effects.
CHUNKY-TO-PLANAR CONVERSION HARDWARE (V40-V44)
GfxBase->ChunkyToPlanarPtr is either NULL, or a pointer to a hardware register used to aid in the process of converting 8-bit chunky pixel data into the bit-plane format used by the Amiga custom display chips. If NULL, then such hardware is not present.
If an expansion device provides hardware which operates compatibly, than it can install the hardware address into this pointer at boot time, and the system will use it.
This pointer may be used for direct access to the chunky-to-planar conversion hardware, if more is desired than the straight chunky-pixel copy that is performed by WriteChunkyPixels().
If using the hardware directly, it should only be accessed when the task using it has control of the blitter (via OwnBlitter()), since this is the locking used to arbitrate usage of this device.
The hardware may be viewed as a device which accepts 32 8-bit chunky pixels and outputs 8 longwords of bitplane data.
For proper operation, exactly 8 longwords (containing 32 pixels) of chunky data should be written to *(GfxBase->ChunkyToPlanarPtr). After the data is written, bitplane data (starting with plane 0) can be read back a longword at a time. There is no need to read back all 8 longwords if the high-order bitplanes are not needed.
Since WriteChunkyPixels() is not particularly fast on systems without the chunky-to-planar hardware, time critical applications (games, etc) may want to use their own custom conversion routine if GfxBase->ChunkyToPlanarPtr is NULL, and call WriteChunkyPixels() otherwise.
This pointer is only present in GfxBase in versions of graphics.library >= 40, so this should be checked before the pointer is read.
BUGS
The emulated WriteChunkyPixels() function used in all Amiga Kickstart ROMs (V40-V44) save for the Amiga CD32 could fail silently if insufficient memory was available.
In V45 speed improved over previous versions, and support for specialized chunky to planar conversion hardware was dropped.
In V45 speed improved over previous versions, and support for specialized chunky to planar conversion hardware was dropped.