ImageCreate
 
Creates and initializes storage for an image

Syntax

Declare Function ImageCreate( width As Integer, height As Integer [, [ color As UInteger ] [, depth As Integer ]] ) As Any Ptr

Usage

buffer = ImageCreate( width, height [, [ color ][, depth ]] )

Parameters

width
Desired width of the image buffer to create.
height
Desired height of the image buffer to create.
color
The pixel value to fill the image buffer with upon creation.
depth
Desired color depth of the image buffer, in bits.

Return Value

The address of the image buffer, or NULL (0) if the buffer could not be created.

Description

Allocates and initializes a memory buffer for an image. If color is omitted, a value of 0 will be used for paletted (8-bit or less) modes, or RGB(255, 0, 255) for higher color depth modes (this translates to &hF81F and &hFFFF00FF for 15/16-bit and 24/32-bit modes, respectively - see the internal gfx formats reference for more info). These are special mask colors, which will be transparent when using Put with the Trans method.

ImageCreate can be used to create an image buffer with a color depth that differs from the current color depth, but only after setting a graphics mode with the Screen statement or ScreenRes statement. An image buffer can be passed to graphics functions across mode changes as long as the different modes use the same color depth.

Images should be deleted with ImageDestroy when they are no longer needed, in order to prevent memory leaks.

The ImageCreate function is an alternative to using the Get (Graphics) statement to create a buffer, and can ease the creation of an image buffer for use 2D drawing functions. It is recommended that you always use ImageCreate though, as it automatically allocates the correct size for the buffer, given its dimensions and the current color depth; the image header may vary in size in future FreeBASIC releases, so using Get (Graphics) with a buffer allocated on the stack may result in corrupted data, as the static buffer size may have been manually computed using a formula that is no longer valid.

Example

'' set screen mode (400 * 300, 32 bits per pixel)
Screen 15, 32

'' allocate and draw to an image buffer
Dim image_buffer As Any Ptr
image_buffer = ImageCreate( 64, 64, RGBA( 64, 160, 0, 255 ) )
Circle image_buffer, ( 32, 32 ), 28, RGBA( 255, 0, 0, 128 ),,,,F

'' blit image buffer to screen
Put( 160, 120 ), image_buffer, PSet
Put( 180, 140 ), image_buffer, Alpha

Sleep

'' free image buffer memory
ImageDestroy( image_buffer )




Dialect Differences

  • Not available in the -lang qb dialect unless referenced with the alias __Imagecreate.

Differences from QB

  • New to FreeBASIC

See also