====== 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 [[:documentation:development:opera:pf25:ppgfldr:pgsfldr:spr:09spr#xref15850|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%%''(), [[:documentation:development:opera:pf25:ppgfldr:ggsfldr:gprfldr:01gpr011#xref24106|DeleteBitmap]](), [[:documentation:development:opera:pf25:ppgfldr:pgsfldr:spr:01spr032#xref18938|DeleteItem]]()