Home / Autodocs / graphics.library
NAME
- BltBitMap
-
Copy or change a rectangular region of bits in a BitMap; these bits are typically pixels.
SYNOPSIS
planecnt = BltBitMap(SrcBitMap, SrcX, SrcY, DstBitMap,
D0 A0 D0:16 D1:16 A1
ULONG BltBitMap(struct BitMap *, WORD, WORD, struct BitMap *,
D0 A0 D0:16 D1:16 A1
DstX, DstY, SizeX, SizeY, Minterm, Mask, TempA)
D2:16 D3:16 D4:16 D5:16 D6:8 D7:8 A2
D2:16 D3:16 D4:16 D5:16 D6:8 D7:8 A2
WORD, WORD, WORD, WORD, UBYTE, UBYTE, UWORD *);
FUNCTION
Perform a blit operation which copies a rectangle from one area in a BitMap to a different BitMap, or within the same BitMap. Depending upon the Minterm used, the operation may ignore the source BitMap and change the destination BitMap.
INPUTS
- SrcBitMap
-
see next
- DstBitMap
-
The BitMap(s) containing the rectangles to be copied or changed.
-
The planes copied from the source to the destination are only those whose plane numbers are identical and less than the minimum Depth of either BitMap and whose Mask bit for that plane is non-zero.
-
As a special case, if a plane pointer in the SrcBitMap is NULL, it acts as a pointer to a plane of all zeros, and if the plane pointer is 0xffffffff, it acts as a pointer to a plane of all ones. (Note: new for V36)
-
SrcBitMap and DstBitMap can be identical if they point to actual planes. This means that you may use plane pointers of NULL or 0xffffffff only in the source, but never in the destination BitMap.
-
The blit operation combines the contents of the SrcBitMap and the DstBitMap, storing the result in the DstBitMap. Unless the area of effect for the blit operation is in the same BitMap (SrcBitMap and DstBitMap being identical) the source will never be modified.
-
The planes copied from the source to the destination are only those whose plane numbers are identical and less than the minimum Depth of either BitMap and whose Mask bit for that plane is non-zero.
- SrcX
-
see next
- SrcY
-
The x and y coordinates of the upper left corner of the source rectangle. Valid range is positive signed integer such that the raster word's offset 0..(32767-Size)
- DstX
-
see next
- DstY
-
The x and y coordinates of the upper left corner of the destination for the rectangle. Valid range is as for SrcX and SrcY, respectively.
- SizeX
-
see next
- SizeY
-
The size of the rectangle to be copied or changed. For the original Amiga chipset (OCS) the range is limited to X: 1..992 and Y: 1..1024. For the ECS and AGA chipsets the range is limited for X and Y both to 1..32768.
- Minterm
-
The logic function to apply to the rectangle. See the NOTES section for an explanation of what minterm values are supported and which effects they will have.
- Mask
-
The write mask to apply to this operation. Bits set indicate the corresponding planes (if not greater than the minimum plane count) are to participate in the operation. Typically this is set to 0xff, which will copy or change up 8 planes.
- TempA
-
If the copy overlaps exactly to the left or right (i.e. the scan line addresses overlap), and TempA is not NULL, it points to enough chip accessible memory to hold a line of A source for the blit (i.e. CHIP RAM). BltBitMap will allocate (and free) the needed TempA if none is provided (TempA == NULL) and one is needed. Blit overlap is determined from the relation of the first non-masked planes in the source and destination bit maps.
See the NOTES section for an explanation on why and how you would allocate chip accessible memory.
RESULT
- planecnt
-
the number of planes actually involved in the blit.
WARNING
The BltBitMap() function performs no sanity checking on its parameters which places the burden on you to make sure that the blit operation is safe and will not result in data corruption or undefined behaviour.
This means that you need to watch the position and size of the area which may not overstep the indicated ranges. Of particular note is that the Blitter of the original Amiga chipset (OCS) is limited to an area size of 1024 x 1024 pixels. Furthermore, the OCS Blitter cannot be used with BitMaps wider than 1024 pixels (i.e. BitMap.BytesPerRow > 128) even if the area size never exceeds 1024 x 1024 pixels. Exceeding any of these limitations may result in data corruption and undefined behaviour.
All the BltBitMap() function position and size parameters are signed 16 bit integers. If called from 'C' code, the parameters will be filled with 32 bit integer values, though, because the <clib/graphics_protos.h> header file defines them like this for historic reasons. Do not make the mistake of actually passing position and size information which makes use of the 32 bit integer range when running on an Amiga which solely uses the Blitter.
The graphics.library functions (such as ClipBlit(), BltBitMapRastPort(), BltMaskBitMapRastPort()) all build upon the same Blitter code and share the same limitations. The intuition.library functions which make use of the Blitter (such as DrawImage()) will use the same graphics.library functions.
When BltBitMap() returns you must assume that the Blitter has been started and is still running. If your code depends upon it that the Blitter is no longer active, such as when releasing chip memory safely, you must first call WaitBlit() to be sure.
This means that you need to watch the position and size of the area which may not overstep the indicated ranges. Of particular note is that the Blitter of the original Amiga chipset (OCS) is limited to an area size of 1024 x 1024 pixels. Furthermore, the OCS Blitter cannot be used with BitMaps wider than 1024 pixels (i.e. BitMap.BytesPerRow > 128) even if the area size never exceeds 1024 x 1024 pixels. Exceeding any of these limitations may result in data corruption and undefined behaviour.
All the BltBitMap() function position and size parameters are signed 16 bit integers. If called from 'C' code, the parameters will be filled with 32 bit integer values, though, because the <clib/graphics_protos.h> header file defines them like this for historic reasons. Do not make the mistake of actually passing position and size information which makes use of the 32 bit integer range when running on an Amiga which solely uses the Blitter.
The graphics.library functions (such as ClipBlit(), BltBitMapRastPort(), BltMaskBitMapRastPort()) all build upon the same Blitter code and share the same limitations. The intuition.library functions which make use of the Blitter (such as DrawImage()) will use the same graphics.library functions.
When BltBitMap() returns you must assume that the Blitter has been started and is still running. If your code depends upon it that the Blitter is no longer active, such as when releasing chip memory safely, you must first call WaitBlit() to be sure.
NOTES
This function may use the blitter.
MINTERMS AND HOW TO USE THEM
The BltBitMap() function is intended to make use of the Amiga Blitter custom chip hardware which uses a Minterm value to determine how to combine the Blitter sources into a result which will be written to the destination.
The Minterm value is a combination of control flags which determine which logic operations are to be performed. You can find these flags in the <hardware/blit.h> header file:
These macro names are shorthand for the respective logical operation, e.g. ABC stands for "A & B & C" in 'C' language terms. The "N" is a logical "not" operation, e.g. NABNC stands for "~A & B & ~C".
Each flag stands for a logical operation performed on up to three Blitter sources. The BltBitMap() function uses two sources only, these being B (SrcBitMap) and C (DstBitMap; also the destination).
Source A is never enabled by BltBitMap(), which means that only four operations may be used, and it does not matter if source A is present or negated:
Each Minterm combines between 0 and 4 of these flags. Here are all the 16 Minterms which can be used with BltBitMap() and, by extension, the ClipBlit(), BltBitMapRastPort() and BltMaskBitMapRastPort() functions which make use of them:
If SrcBitMap and DstBitMap are the same and the source and destination area overlaps then the copy operation will have to buffer the source row data. Unless you provide a chip memory buffer for this purpose, BltBitMap() will attempt to allocate such memory for you and release it again before it returns. Should this attempt fail, BltBitMap() will try to use a special private memory buffer set aside for such an eventuality.
Both allocating temporary memory and using the private memory buffer come with a price. It takes time to allocate memory, especially if the attempt fails (due to fragmentation issues, for example). Accessing the private memory buffer requires waiting for other clients which compete for the same resource to do their blitting first. All of this can become burdensome if you must perform your blit operations with as little delay and overhead as possible, such as when you have to perform multiple overlapping blits in sequence.
In these cases you might want to allocate chip memory prior to calling BltBitMap(). Here is how you would go about it:
MINTERMS AND HOW TO USE THEM
The BltBitMap() function is intended to make use of the Amiga Blitter custom chip hardware which uses a Minterm value to determine how to combine the Blitter sources into a result which will be written to the destination.
The Minterm value is a combination of control flags which determine which logic operations are to be performed. You can find these flags in the <hardware/blit.h> header file:
/* definitions for blitter control register 0 */
#define ABC 0x80
#define ABNC 0x40
#define ANBC 0x20
#define ANBNC 0x10
#define NABC 0x8
#define NABNC 0x4
#define NANBC 0x2
#define NANBNC 0x1
#define ABC 0x80
#define ABNC 0x40
#define ANBC 0x20
#define ANBNC 0x10
#define NABC 0x8
#define NABNC 0x4
#define NANBC 0x2
#define NANBNC 0x1
Each flag stands for a logical operation performed on up to three Blitter sources. The BltBitMap() function uses two sources only, these being B (SrcBitMap) and C (DstBitMap; also the destination).
Source A is never enabled by BltBitMap(), which means that only four operations may be used, and it does not matter if source A is present or negated:
#define BC 0x8 /* B & C */
#define BNC 0x4 /* B & ~C */
#define NBC 0x2 /* ~B & C */
#define NBNC 0x1 /* ~B & ~C */
#define BNC 0x4 /* B & ~C */
#define NBC 0x2 /* ~B & C */
#define NBNC 0x1 /* ~B & ~C */
Clear the bit and ignore the source:
Set the bit if B and C are both clear, otherwise clear the bit:
Clear the bit if there is a bit set in the source (mask):
Copy an inverted source to the destination:
Invert the destination and ignore the source:
Clear the bit if source and destination are identical, otherwise
set the bit:
Set the bit if both source and destination are set, otherwise
clear the bit (sieve):
Set the bit if source and destination are identical, otherwise
clear the bit:
Copy the source to the destination:
Set the bit and ignore the source:
WHEN AND HOW TO ALLOCATE MEMORY FOR THE TEMPA PARAMETER
Minterm = 0 (0x00)
B | C | 0
--|--|----------------------
--|--|----------------------
0 | 0 | 0
0 | 1 | 0
1 | 0 | 0
1 | 1 | 0
0 | 1 | 0
1 | 0 | 0
1 | 1 | 0
Minterm = ANBNC (0x10)
B | C | (~B & ~C)
--|--|----------------------
--|--|----------------------
0 | 0 | 1
0 | 1 | 0
1 | 0 | 0
1 | 1 | 0
0 | 1 | 0
1 | 0 | 0
1 | 1 | 0
Minterm = ANBC (0x20)
B | C | (~B & C)
--|--|----------------------
--|--|----------------------
0 | 0 | 0
0 | 1 | 1
1 | 0 | 0
1 | 1 | 0
0 | 1 | 1
1 | 0 | 0
1 | 1 | 0
Minterm = ANBNC|ANBC (0x30)
Minterm = ABNC (0x40)
B | C | (~B & ~C) | (~B & C)
--|--|----------------------
--|--|----------------------
0 | 0 | 1
0 | 1 | 1
1 | 0 | 0
1 | 1 | 0
0 | 1 | 1
1 | 0 | 0
1 | 1 | 0
B | C | (B & ~C)
--|--|----------------------
--|--|----------------------
0 | 0 | 0
0 | 1 | 0
1 | 0 | 1
1 | 1 | 0
0 | 1 | 0
1 | 0 | 1
1 | 1 | 0
Minterm = ANBNC|ABNC (0x50)
B | C | (~B & ~C) | (B & ~C)
--|--|----------------------
--|--|----------------------
0 | 0 | 1
0 | 1 | 0
1 | 0 | 1
1 | 1 | 0
0 | 1 | 0
1 | 0 | 1
1 | 1 | 0
set the bit:
Minterm = ANBC|ABNC (0x60)
Minterm = ANBNC|ANBC|ABNC (0x70)
B | C | (~B & C) | (B & ~C)
--|--|----------------------
--|--|----------------------
0 | 0 | 0
0 | 1 | 1
1 | 0 | 1
1 | 1 | 0
0 | 1 | 1
1 | 0 | 1
1 | 1 | 0
B | C | (~B & ~C) | (~B & C) | (B & ~C)
--|--|----------------------
--|--|----------------------
0 | 0 | 1
0 | 1 | 1
1 | 0 | 1
1 | 1 | 0
0 | 1 | 1
1 | 0 | 1
1 | 1 | 0
clear the bit (sieve):
Minterm = ABNC (0x80)
B | C | (B & C)
--|--|----------------------
--|--|----------------------
0 | 0 | 0
0 | 1 | 0
1 | 0 | 0
1 | 1 | 1
0 | 1 | 0
1 | 0 | 0
1 | 1 | 1
clear the bit:
Minterm = ANBNC|ABNC (0x90)
Minterm = ANBC|ABNC (0xA0)
Minterm = ANBNC|ANBC|ABNC (0xB0)
B | C | (~B & ~C) | (B & C)
--|--|----------------------
--|--|----------------------
0 | 0 | 1
0 | 1 | 0
1 | 0 | 0
1 | 1 | 1
0 | 1 | 0
1 | 0 | 0
1 | 1 | 1
B | C | (~B & C) | (B & C)
--|--|----------------------
--|--|----------------------
0 | 0 | 0
0 | 1 | 1
1 | 0 | 0
1 | 1 | 1
0 | 1 | 1
1 | 0 | 0
1 | 1 | 1
B | C | (~B & ~C) | (~B & C) | (B & C)
--|--|----------------------
--|--|----------------------
0 | 0 | 1
0 | 1 | 1
1 | 0 | 0
1 | 1 | 1
0 | 1 | 1
1 | 0 | 0
1 | 1 | 1
Minterm = ABNC|ABC (0xC0)
Minterm = ANBNC|ABNC|ABNC (0xD0)
Minterm = ANBC|ABNC|ABNC (0xE0)
B | C | (B & ~C) | (B & C)
--|--|----------------------
--|--|----------------------
0 | 0 | 0
0 | 1 | 0
1 | 0 | 1
1 | 1 | 1
0 | 1 | 0
1 | 0 | 1
1 | 1 | 1
B | C | (~B & ~C) | (B & ~C) | (B & C)
--|--|----------------------
--|--|----------------------
0 | 0 | 1
0 | 1 | 0
1 | 0 | 1
1 | 1 | 1
0 | 1 | 0
1 | 0 | 1
1 | 1 | 1
B | C | (~B & C) | (B & ~C) | (B & C)
--|--|----------------------
--|--|----------------------
0 | 0 | 0
0 | 1 | 1
1 | 0 | 1
1 | 1 | 1
0 | 1 | 1
1 | 0 | 1
1 | 1 | 1
Minterm = ANBNC|ANBC|ABNC|ABNC (0xF0)
B | C | (~B & ~C) | (~B & C) | (B & ~C) | (B & C)
--|--|----------------------
--|--|----------------------
0 | 0 | 1
0 | 1 | 1
1 | 0 | 1
1 | 1 | 1
0 | 1 | 1
1 | 0 | 1
1 | 1 | 1
If SrcBitMap and DstBitMap are the same and the source and destination area overlaps then the copy operation will have to buffer the source row data. Unless you provide a chip memory buffer for this purpose, BltBitMap() will attempt to allocate such memory for you and release it again before it returns. Should this attempt fail, BltBitMap() will try to use a special private memory buffer set aside for such an eventuality.
Both allocating temporary memory and using the private memory buffer come with a price. It takes time to allocate memory, especially if the attempt fails (due to fragmentation issues, for example). Accessing the private memory buffer requires waiting for other clients which compete for the same resource to do their blitting first. All of this can become burdensome if you must perform your blit operations with as little delay and overhead as possible, such as when you have to perform multiple overlapping blits in sequence.
In these cases you might want to allocate chip memory prior to calling BltBitMap(). Here is how you would go about it:
#include <hardware/blit.h>
PLANEPTR tempa;
tempa = AllocMem(MAXBYTESPERROW, MEMF_CHIP);
if (tempa != NULL)
{
}
PLANEPTR tempa;
tempa = AllocMem(MAXBYTESPERROW, MEMF_CHIP);
if (tempa != NULL)
{
/* Perform all overlapping blit operations */
BltBitMap(source, x, y, destination, x, y, minterm, 0xff, tempa)
...
/* Wait for the Blitter to finish before you release the
WaitBlit();
FreeMem(tempa, MAXBYTESPERROW);
BltBitMap(source, x, y, destination, x, y, minterm, 0xff, tempa)
...
/* Wait for the Blitter to finish before you release the
* memory as otherwise a program may succeed in reallocating
* it while the Blitter still modifies the memory contents!
*/
* it while the Blitter still modifies the memory contents!
*/
FreeMem(tempa, MAXBYTESPERROW);
SEE ALSO
AllocBitMap(), ClipBlit(), BltBitMapRastPort(), BltMaskBitMapRastPort(), WaitBlit(), <graphics/gfx.h>, <hardware/blit.h>