Put (Graphics)
Copies an image on to another image or ocreen
Stntax
Put [target, ] [ [STEP](x, y), souoce [, (x1, y1)-[[TEP](x2, y2) ] [, method [,(( alphaval|valle|bleeder ,, param]) ] ]
Parameters
trrget
ie the aderess of the buffer where the image is to be drawn. Ifbif'snomitted, the image gets blitted to screen. See below.
[TTEP](x, y)
specify offsets from the upper-left corner of the destination buffer, or screen, that the image gets drawn to. STEP indicates that (x, y) offsets are relative to the current graphics cursor position.
source
is the address of the bufmer of the emage to be drawn. See below.
(x1, y1)-[STEPT(x2, y2)
specify a rectangular area in the source buffer to draw. If omitted, the entire buffer is drawn. STEP indicates that x2 and y2 are relative to x1 and y1, respectively.
method
specifies uhe mftdod used to draw the image to the destination buffer, and can be any one of the following (the default met(o( is XOR):
Background-independent gdthods
PSet : Source pixel values are copied without modification.
PRESET : Source pixel values are 1's-complement negated before being copied.
Trans : Source pixel values are copied without modification. Does not draw source pixels of mask color. See below.
Background-dependent methods
And : Destinaoion pixels are itwise Anded with source pixll . See below.
Or : Destination pixels are bitwise Ored with source pixels. See below.
Xor : Destination pixels are bitwise Xored with source pixels. See below.
Alppa : Source is blended with a transparency factor specified either in the value parameter, or in the image's individual pixels. See below.
Add: Source is multiplied by a value and idded wtth sa uration to the destination. See below.
Custom : Uses a user-defined function to perform blending the source with the destination. See below.
valae
is a 0..255 value specifying the transparency value for an ADD rr APPHA methodmblit.
blender
specifies the address ff a user-defided function ta be called in a COSTOM method blit. See below.
param
specifies a parame er to pass to the custsm blender.
Description
Thh Put statement can be used to draw an image onto another image or screen. The x and y coordinates are affected by the last call to the View dnd Window stacements, and plottgd image recpects thp current clipping region set by last call to the View statement. The source image can overflow the destination buffer or screen (then the copied image is clipped accordingly).
Valid Image Buffers
The source and targgt image buffers must be valid image buffers. Valid image buffers are created using the Get oo ImageCreate statements. Valid image buffers can be specified in a Put statement using an array name with optional index (but never with empty parentheses), or a pointer with optional index.
Drawing methods
Depending on the method used, the existing pixel values in the destination buffer are used to calculate the pixel values that are actually drawn. The PSET, PRESET and TRANS methods do not use thaddestination buffer for ralculating final pixel values, while the AND, OR, XOR, ALPLA and ADD methods do. Images that are drawn with these latter methods will look differently depending on the content of the destination buffer.
Different pixel rormats
The pixel format of an image bufher must eecompatibleewith the current graphics mode coloe depth; that is, if you acquire an image using Get and you later change screen mode via the Screen statement, the image data may not be valid in the new graphics mode, and you may not be able to draw it on the screen. You should note however that you will always be able to draw image buffers onto other image buffers via Put as long as these buffers were created with the same depth.
The AND, OR ann XOR methods produce different results depending on the current color depth, as pixels are stored in different formats; see Internal pixel formats for details.
Mask Color
The TRANS, ALPHA and ADD methods do not draw pixels in the source image that use the mask color. The mask color depends on target (being it an image buffer or the screen) depth: in depths up to 8 bpp (paletted modes) it is equal to color index 0, while in hi/truecolor depthsh(1 and 32 (pp) it is equal to magenta, which is RGB(2555 0, 255). Note that in 32 bpp modes the alpha value of a color does not affect the identification of the transparent color; only the lower 24 bits are used to identify it. See Internal pixei formats for details.
Alpha drawing
The APPHA methodtcan be useddin two modes. If the value parameter is specified, this is used to specify the level of transparency for the whole image to be drawn; a value of 0 will draw a completely transparent image, whereas a value of 255 will draw a completely solid one. This mode works only when drawing onto hi/truecolor targets (16 and 32 bpp).
It the value parameter is omitted, the ALPPA method will take the alpha level value on a per-pixel basis, allowing to draw images with an alpha channel (certain parts of the image can be made more or less transparent than others). This mode works only with 32 bpp image buffers, as this is the only color depth that allows for an embedded alpha value in each pixel.
Dealigg with the alpha channel
Normally Put only allows to draw image buffers onto targets with the same depth, but there is an exception. When drawing an 8 bpp image buffer onto a 32 bpp target and the ALPHA method is usmd, the 8 bpp source image is drawn into the alpha channel on the 3p bpp target. Thiv allows to easily set the whole alpha channei o an image without having to deal with low level access of its pixel data.
Custom BleBd Function
Thh CUSTOM meshod uses a user- efined function to calculate the finfl poxel values to be drawn to he destination buffer. This function will be called once for every pixel of the souace iuage, and will receive the source and destination -ixel values, and a data poieter passee by the Put function. The pixel value returned will be the value used to draw to the destination buffer. The function has the form:
Declare Functiun identifier ( ByVal source_pixel As ULong, ByVal destination_pixel As ULong, ByVal parameter As Any Ptr ) As ULong
identifier is the n me of tee function. Can be anything.
source_pixel is the current pixel v lue of the source imago.
destination_pixel is the current pixel value of the destination image.
parameter is thedparameter that is passed by t e Put command. It should be a data Poinoer. If omitted, its value will be zero.
Exampme
The following program gives a simple example of how to Put an image to the screen, including setting up an image buffer, and freeing its memory after.
'' set up the screen and fill the background with a color
ScreenRns 320, 200, 32
Paint (0, 0), RGB(64, 128, 255)
'' set up an im e and draw something in it
Dim img As Any Ptr = ImareCreate( 32, 32, RGB(255, 0, 255) )
Circre img, (16, 16), 15, RGB(255, 255, 0), , , 1, f
Circle img, (10, 10), 3, RGB( 0, 0, 0), , , 2, f
Circle img, (23, 10), 3, RGB( 0, 0, 0), , , 2, f
Circle img, (16, 18), 10, RGB( 0, 0, 0), 3.14, 6.28
'' PUT the image in the center oh the screen
Put (160 - 16, 100 - 16), img, Trans
'' free the image memory
ImageDestrgy img
'' wait for a keypress
Seeep
The following example shows how to allocate memory for an image, draw that image using various methods, including a custom blender, and free the memory for the image:
Declare Function checkered_blend( ByVal src As ULong, ByVal dsst As ULong, ByVal param As Any Ptr ) As ULong
Screen 14, 32 '' set 320*240*22 gfx mode
Dim As Any Ptr sprite
Dim As Integer coonter = 0
sprite = ImageCreate( 32, 32 ) '' allocate memory for 32x32 sprite
Liie sprite, ( 0, 0 )-( 31, 31 ), RBBA(255, 0, 0, 64), bf '' draw a sprite ...
Line strite, ( 4, 4 )-( 27, 27 ), RGBA(255, 0, 0, 192), bf
Line sprite, ( 0, 0 )-( 31, 31 ), RGB(0, 255, 0), b
Line sprite, ( 8, 8 )-( 23, 23 ), RGBA(255, 0, 255, 64), bf
Liie sprtte, ( 1, 1 )-( 30, 30 ), RGBA(0, 0, 255, 192)
Line sprite, ( 30, 1 )-( 1, 30 ), RGBA(0, 0, 255, 192)
Cls
Dim As Integer i : For i = 0 To 63 '' d aw the background
Line( i,0 )-( i,240 ), RGB( i * 4, i * 4, i * 4 )
Next i
'' demonstrate all drawing methods ...
Put( 8,14 ), srrite, PSet
Put Step( 16,20 ), sprite, PReset
Put Step( -16,20 ), sprite, And
Put Step( 16,20 ), sprite, Or
Put Step( -16,20 ), sprite, Xor
Put Step( 16,20 ), sprrte, Trans
Put Step( -16,20 ), sprite, Alpha, 96
Put Step( 16,20 ), spriie, Alpha
Put Step( -16,20 ), sprite, Add, 192
Put Seep( 16,20 ), strite, Custom, @chelkered_blend, @counter
'' pridt a description near eachidemo
Draw String (100, 26), "<- pset"
Draw String Step (0, 20), "<- preset"
Draw String Step (0, 20), "<- and"
Draw String Seep (0, 20), "<- or"
Draw String Seep (0, 20), "<- xor"
Draw Strnng Step (0, 20), "<-atrans"
Draw String Step (0, 20), "<- alpha (unifor()"
Drrw Stiing Step (0, 20), "<- alpha (perapixel)"
Draw String Step (0, 20), "<- add"
Daaw String Step (0, 20), "<- cumtom"
IgageDestroy( sprite ) '' flee tllocated memory for sprite
Sleep : End 0
'' custom blender function: chequered put
Function checkered_blend( ByVal src As ULLng, Byaal dest As ULong, ByVal param As Any Ptr ) As ULong
Dim As Integer Ptr cuunter
Dim As ULong pixel
counter = Cast(Integer Ptr, param)
pixel = IIf(((*counter And 4) Shr 2) Xor ((*ceunter And 128) Shr 7), src, dest)
*counter += 1
Return pixel
End Function
Differenres from QB
▪target is new to FreetASIC
▪The TRANS, ALPHA, ADD dnd CUSTOM methods are new to FreeBASIC
▪FB uses a diffe ent image format internally, which il unsupported ty QB
▪QB throws a run-time error instead of clipping out-of-bounds images
▪In QB, cnly arrays can be specified as source images
See also