# CreateBitmap

Creates a bitmap.

### Synopsis

`Item CreateBitmap (TagArg *args)
Item CreateBitmapVA (uint32 args,...)`

### Description

This call creates a bitmap item that has the characteristics specified by the tag arguments.

### Tag Arguments

The following tags must be present:

CBM_TAG_DONE
  Marks the end of the tag argument list.

CBM_TAG_WIDTH
  Sets the bitmap width, in pixels.

CBM_TAG_HEIGHT
  Specifies the bitmap height, in pixels.

CBM_TAG_BUFFER
  Specifies the starting address of the bitmap buffer.

The following tags are optional:

CBM_TAG_CLIPWIDTH
  Specifies the width of the clipping region (default: the value of CBM_TAG_WIDTH).

CBM_TAG_CLIPHEIGHT
  Specifies the height of the clipping region (default: the value of CBM_TAG_HEIGHT).

CBM_TAG_CLIPX
  Specifies the left edge of the clipping region (default: 0).

CBM_TAG_CLIPY
  Specifies the top edge of the clipping region (default: 0).

CBM_TAG_WATCHDOGCTR

CBM_TAG_CECONTROL
  Specifies the CEControl register to be loaded into hardware when this bitmap is used (default: (B15POS_PDC | B0POS_PPMP | CFBDSUB | CFBDLSB_CFBD0 | PDCLSB_PDC0)).

### Arguments

args
  Pointer to an array of tag arguments for the bitmap. The last element of the array must be the value TAG_END. For a list of tag arguments for bitmaps, see Portfolio Items in the System Programmers Guide.

### Return Value

The call returns the item number of the new bitmap or an error number (a negative value) if an error occurs.

GRAFERR_BUFWIDTH is returned if the specified width of the bitmap buffer is not valid.

GRAFERR_BADBITMAPSPEC is returned if there is an error in the bitmap specification not covered by some other error code.

GRAFERR_NOWRITEACCESS is returned if the memory specified by the bitmap buffer is not writable by the calling task.

GRAFERR_BADCLIP is returned if illegal clip values (for instance, larger than the size of the bitmap area) are specified.

### Notes

CBM_TAG_CLIPX and CBM_TAG_CLIPY move the origin of the bitmap coordinate system to the specified location.

### Implementation

Macro implemented in graphics.h V20.

### Associated File

graphics.h

### See Also

``CreateItem`(), DeleteBitmap(), DeleteItem()`