AllocBitMap

Allocate a bitmap and attach bitplanes to it. (V39)

Allocates and initializes a bitmap structure. Allocates and initializes bitplane data, and sets the bitmap's planes to point to it.

sizex

The width (in pixels) desired for the bitmap data.

CAUTION:

AllocBitMap() will return NULL if the BitMap width exceeds 32760 pixels on ECS or AGA systems.

No such check is performed on Amigas using the original Amiga custom chipset (OCS). You should never request a BitMap wider than 1024 pixels on an OCS Amiga and actively prevent it from getting created by your code!

sizey

The height (in pixels) desired.

depth

The number of bitplanes deep for the allocation. Pixels with AT LEAST this many bits will be allocated.

flags

A combination of the following:

BMF_CLEAR to specify that the allocated raster should be filled with color 0.

BMF_DISPLAYABLE to specify that this bitmap data should be allocated in such a manner that it can be displayed. Displayable data has more severe alignment restrictions than non-displayable data in some systems.

BMF_INTERLEAVED tells graphics that you would like your bitmap to be allocated with one large chunk of display memory for all bitplanes. This minimizes color flashing on deep displays.

CAUTION:

The BMF_INTERLEAVED flag is ignored on Amigas which use the Original Amiga custom chipset (OCS). You need either the ECS or AGA custom chipsets to create interleaved BitMaps with AllocBitMap().

CAUTION:

If there is not enough contiguous RAM for an interleaved bitmap, AllocBitMap() will return NULL.

BMF_MINPLANES causes graphics to only allocate enough space in the bitmap structure for "depth" plane pointers. This is for system use and should not be used by applications use as it is inefficient, and may waste memory.

BMF_RTGTAGS, BMF_RTGCHECK and BMF_FRIENDISTAG - If these three flags are set in combination, then friend_bitmap is, actually, a pointer to a taglist, see <utility/tagitem.h>. This taglist contains items that defines additional parameters that may be useful to create the bitmap (see below).

friend_bitmap

Pointer to another bitmap, or a pointer to a 'struct TagItem *' if BMF_RTGTAGS|BMF_RTGCHECK|BMF_FRIENDISTAG flags are all set or NULL.

If this pointer is a bitmap (regular case), then the bitmap data will be allocated in the most efficient form for blitting to friend_bitmap.

If this pointer is a pointer to a taglist, the tags defined in <graphics/gfx.h> may be recognized to allocate a bitmap for most efficient usage.

BMATags_Friend

A pointer to a friend bitmap, substituting the argument that would otherwise go into the friend_bitmap pointer.

BMATags_Depth

An integer specifying the depth. The default is the depth parameter passed in as argument.

BMATags_PixelFormat

An RTG graphics dependent pixel format the bitmap shall be allocated for.

BMATags_Clear

A boolean tag which, if set, instructs the bitmap to be cleared. Default is the value of the BMF_CLEAR flag.

BMATags_Displayable

A boolean tag which, if set, instructs the RTG graphics to allocate the bitmap such that it is possible to program the display hardware to output the contents of the bitmap. Default is the value of the BMF_DISPLAYABLE flag.

BMATags_NoMemory

A boolean tag which instructs the RTG library to only allocate a 'struct BitMap' that is native to the RTG system, though do not allocate any display memory for it. Default is FALSE, i.e. memory will be allocated.

Note that 'BMATags_NoMemory, TRUE' will result in not allocating any memory and 'BMATags_NoMemory, FALSE' will attempt to allocate memory.

BMATags_NoSprite

A boolean tag which, if set, disables the generation of a sprite/mouse pointer if this bitmap is loaded to the video hardware. Default is FALSE, i.e. a sprite/mouse pointer will be generated.

Note that 'BMATags_NoSprite, TRUE,' will inhibit the generation of a sprite/mouse pointer and 'BMATags_NoSprite, FALSE,' will generate a sprite/mode pointer.

BMATags_ModeWidth

Width of the display mode in pixels that shall be generated if this bitmap is loaded to the video hardware. Default is the native width of the DisplayID.

BMATags_ModeHeight

Height of the display mode in lines that shall be generated if this bitmap is loaded to the video hardware. Default is the native height of the DisplayID.

BMATags_DisplayID

Mode ID from the display info database for which this bitmap is supposed to be allocated. This hint may provide an RTG system with all the necessary information how to layout the bitmap such that it can be loaded into the video hardware. The tag ID of this tag is intentionally identical to SA_DisplayID.

BMATags_BitmapInvisible

A boolean tag which, if set, instructs the RTG system to allocate the bitmap in an off-hardware location, such as fast memory. The bitmap is then relocated to on-board memory as soon as necessary, e.g. when the screen it is allocated for is moved frontmost. Default for this tag is FALSE.

It is recommended to allocate bitmaps for screens that are opened to appear behind the frontmost screen with this tag set to avoid wasteful allocation of on-board memory. The tag ID of this tag is intentionally identical to SA_Behind.

BMATags_BitmapColors

A pointer to an array of 'struct ColorSpec', terminated by ColorIndex = -1. This array specifies the initial screen palette colors. The tag ID of this tag is intentionally identical to SA_Colors. Default for this tag is NULL.

BMATags_BitmapColors32

A pointer to an array of ULONGs that specifies the initial palette colors with 32 bits per component. That is, 32 bits for red, 32 bits for green and 32 bits for blue. Default for this tag is NULL.

The tag data is a pointer that could be passed into LoadRGB32(). Any color set here has precedence over the same register set by ABMA_BitmapColors. Intentionally identical to SA_Colors32

Returns a pointer to a 'struct BitMap' or NULL in case of failure.

NULL will be returned if there is not enough contiguous RAM available to allocate an interleaved BitMap. Even if there is still nominally enough RAM available, the constraints of an interleaved BitMap render it unusable.

NULL will be returned if the requested BitMap width exceeds 32760 pixels on an ECS or AGA system.

Interleaved BitMaps are a crucial building block of the Amiga graphics system and its hardware. You are bound to make use of them, but you should be aware of their limitations and the constraints which govern their proper use.

Exceeding these limitations will lead to software errors and data corruption, whose causes are difficult to track down. The graphics.library Blitter functions do not provide protection against accidental misuse.

Note:

These constraints are subtle because interleaved BitMaps are not merely an extension of the BitMaps which you are already familiar with. There are side-effects which must be accounted for.

The AllocBitMap() function was introduced in Kickstart 3.0. Prior to this the creation of a BitMap suitable for both display purposes and Blitter operations went along the following steps:

The memory bandwidth requirements of the AGA chipset made it necessary for bit planes not to be allocated separately, as illustrated by this example.

Preferably, the memory contents representing each line of graphics should be close by so that the display hardware could fetch all of it in a single sweep. This is what the interleaved bitmap format enables and why the AllocBitMap() function exists which creates this special type of BitMap.

• For the BitMap "interleaving" means that all the planes of a single BitMap row directly follow one another in memory. For an interleaved BitMap the BitMap.BytesPerRow value will be affected by the BitMap depth. For the example above which constructed a BitMap using InitBitMap() and AllocRaster() you would find that invoking AllocBitMap() with width=320, depth=4 and requesting the BitMap to be interleaved, the BitMap.BytesPerRow value will be 4 * 40 = 160 bytes instead of 40.
  
  

  CAUTION:

  The number of bytes per row are no longer both the row modulus and an indication of the width of each row for an interleaved BitMap.
  
  

• AllocBitMap() allocates the interleaved plane data, taking alignment requirements into account (e.g. AGA requires that each row of image data must be aligned to a 64 bit address, i.e. a multiple of 8 bytes), in a single consecutive chunk.
  
  

  CAUTION:

  Memory fragmentation constraints may cause the allocation to fail entirely.
  
  

• The ECS and AGA Blitter cannot handle BitMaps with BytesPerRow values exceeding 4095 bytes. Which means that interleaved BitMaps on the ECS and AGA chipsets are constrained to width * depth <= 4095 (approximately).
  
  The maximum BitMap height which the Blitter can access is reduced, too. For the ECS and AGA chipsets the height is limited to 32768 / depth pixels (approximately).
  
  

  CAUTION:

  AllocBitMap() permits you to allocate BitMaps which exceed these dimensions. But you should be aware that you may be unable to use them with the Blitter when running on a system which exclusively uses the Amiga custom chipset.
  
  For Amigas which use the original chipset (OCS) no sanity check is performed when BitMaps wider than 1024 pixels are requested. The operating system will try to satisfy your request even though the resulting BitMap will be unsafe to use. You should catch such cases before the call to AllocBitMap() is made!
  
  If you still try, the results may lead to software errors and data corruption.
  
  

When allocating using a friend bitmap, it is not safe to assume anything about the structure of the bitmap data if that friend BitMap might not be a standard amiga bitmap.

For instance, if the workbench is running on a non-amiga display device, its Screen->RastPort->BitMap won't be in standard Amiga format. The only safe operations to perform on a non-standard BitMap are:

• blitting it to another bitmap, which must be either a standard Amiga bitmap, or a friend of this bitmap.
  
  
• blitting from this bitmap to a friend bitmap or to a standard Amiga bitmap.
  
  
• attaching it to a rastport and making rendering calls.
  
  

Good arguments to pass for the friend_bitmap are your window's RPort->BitMap, and your screen's RastPort->BitMap. Do NOT pass &(screenptr->BitMap)!

BitMaps not allocated with BMF_DISPLAYABLE may not be used as Intuition Custom BitMaps or as RasInfo->BitMaps. They may be blitted to a BMF_DISPLAYABLE BitMap, using one of the BltBitMap() family of functions.

The taglist which AllocBitMap() accepts with the flag combination of BMF_RTGTAGS|BMF_RTGCHECK|BMF_FRIENDISTAG uses tag IDs that are intentionally identical to those of OpenScreenTagList().

It is good practise, which is in fact followed by intuition V47, to pass over the taglist used for creating a screen to this function to receive a bitmap that is suitable for the specific mode ID and screen dimensions.

FreeBitMap(), LoadRGB32(), OpenScreenTagList()