QB64-PE/internal/help/PUT_(graphics_statement).txt

The '''PUT''' graphics statement is used to place [[GET (graphics statement)|GET]] or [[BSAVE]] file images stored in the designated array.


{{PageSyntax}} 

:: '''PUT''' [{{KW|STEP}}]'''(''column'', ''row''), Array('''[''index'']''')'''[,] [{{KW|_CLIP}}]  [{PSET|PRESET|AND|OR|XOR}]][, ''omitcolor'']


''[[Parameters]]:''
* The [[STEP]] keyword can be used to for coordinates relative to the last graphic coordinates used.
* ''column'' and ''row'' [[INTEGER]] coordinate values designate the top left corner where the image is to be placed and cannot be off screen.
* The [[INTEGER]] ''array'' holds data of an image box area created by [[GET (graphics statement)|GET]]. The brackets can be empty or designate a starting ''index''.
* [[_CLIP]] can be used in QB64 when part of an image must be off screen.
* [[XOR]], [[PSET]], [[PRESET]], [[OR]] or [[AND]] actions will affect the coloring of the image on certain background colors. See below.
* ''omitcolor'' is the pixel color attribute to ignore in QB64 only. This may be used instead of using an [[AND]] mask.


''Usage:''
* '''The entire box area of the image MUST be on the screen or an "Illegal function call" [[ERROR Codes|error]] will occur!'''
* In '''QB64''' [[_CLIP]] can be used when part of the image may be off of the screen. This will also prevent off screen errors!
::PUT (-10, 10), mypic(0), PSET ' this causes an illegal function call without [[_CLIP]]
::PUT (-10, 10), mypic(0), _CLIP PSET ' allows a graphic to be placed partially off-screen
::PUT (-10, 10), mypic(0), _CLIP ' uses the default PUT XOR operation
::PUT (-10, 10), mypic(0), _CLIP PSET, 4 ' doesn't place the red pixels of the image
* In '''QB64''' a background color attribute can be removed from the PUT image using the ''omit color'' option instead of creating a mask.
* The [[arrays|array]] must have image data at the array index given. [[GET (graphics statement)|GET]] or [[BLOAD]] should be used to place image data into the array.
* The [[INTEGER]] array size can be calculated as slightly larger than the box area width times the height. A closer estimate can be done by reading the array indices from [[UBOUND]] to [[LBOUND]] after a [[GET (graphics statement)|GET]] of a white box area. In QB64 a [[LONG]] array can be used for large or full screen images.
* If no [[arrays|array]] index (brackets optional in QB) is designated, the image will be assumed to be at the array's starting index.
* The first two indices of the [[arrays|array]] or array offset will hold the width and height of the stored image area. In [[SCREEN]] 13 divide the width by 8.
* More than one image can be stored in the [[INTEGER]] array by indexing the [[GET (graphics statement)|GET]] array offset. Be sure the index is not already used!
* A [[_DEST]] [[handle]] can be set to PUT images elsewhere other than on the current screen. Use [[_SOURCE]] to [[GET (graphics statement)|GET]] images there.
* If no color action is listed after the image array, the action will be assumed to be the default [[XOR]]. 
::* [[XOR]] may blend with background colors, but can be used to erase an image when placed a second time.
::* [[PSET]] completely overwrites any background with the identical image.
::* [[PRESET]] creates a inverted coloring of the original image completely overwriting the background.
::* [[AND]] merges background colors with the black areas of the image where a white image mask is used.
::* [[OR]] blends the background and foreground colors together.
* In QB64 [[_PUTIMAGE]] is recommended over PUT as it can also do the [[GET (graphics statement)|GET]] directly from the image source without requiring an array.
* [[PUT]] and [[GET]] file statements can also write and read image array data using [[BINARY]] files instead of using [[BSAVE]] or [[BLOAD]].


''Example 1:'' How [[GET]] and PUT can be used with images loaded with [[_LOADIMAGE]]. The background color is omitted or "masked".
{{CodeStart}} '' ''
{{Cl|SCREEN (statement)|SCREEN}} {{Cl|_NEWIMAGE}}(640, 480, 256)
{{Cl|_SCREENMOVE}} {{Cl|_SCREENMOVE|_MIDDLE}}
image& = {{Cl|_LOADIMAGE}}("QB64.png")

wide& = {{Cl|_WIDTH (function)|_WIDTH}}(image&): deep& = {{Cl|_HEIGHT}}(image&)
{{Cl|DIM}} Array(wide& * deep&) {{Cl|AS}} {{Cl|INTEGER}}

{{Cl|_SOURCE}} image&              'REQUIRED to GET the proper image area!
{{Cl|GET (graphics statement)|GET}} (0, 0)-(wide& - 1, deep& - 1), Array(0)

{{Cl|_DEST}} 0
{{Cl|_COPYPALETTE}} image&, 0      'necessary for custom image colors other than screen defaults
{{Cl|PUT (graphics statement)|PUT}}(10, 10), Array(0), {{Cl|PSET}} , {{Cl|_RGB}}(255, 255, 255)   'mask white background color
{{Cl|END}} '' ''
{{CodeEnd}}
: ''Explanation:'' '''QB64''' allows one PUT color to be "masked" to allow odd shaped sprite image backgrounds to be transparent.


''Example 2:'' Using a [[STRING]] instead of an [[arrays|array]] to store [[GET]] image data that can be PUT later. For images up to 256 colors only.
{{CodeStart}} '' ''
a$ = {{Cl|SPACE$}}(4 + 100)            '4 byte header + 100 pixels for a 10 X 10 image
{{Cl|SCREEN}} 13
{{Cl|LINE}} (0, 0)-(319, 199), 4, BF   'color 4 = CHR$(4) = ♦
{{Cl|LINE}} (40, 40)-(49, 49), 14, B   'color 14 = CHR$(14) = ♫
{{Cl|GET (graphics statement)|GET}} (40, 40)-(49, 49), a$

K$ = {{Cl|INPUT$}}(1)

{{Cl|CLS}}
{{Cl|PRINT}} a$                        'display string data. Width = {{Cl|CHR$}}(10 * 8) = "P"
{{Cl|PUT (graphics statement)|PUT}}(100, 100), a$, {{Cl|PSET}} '' ''
{{CodeEnd}}
{{small|Code by Galleon}}
: ''Explanation:'' The header holds the [[INTEGER]] width and depth of the image area as 2 bytes each. Screen 13 width is multiplied by 8.


''See also:'' 
* [[_PUTIMAGE]], [[_LOADIMAGE]]
* [[_MAPTRIANGLE]]
* [[GET (graphics statement)|GET]], [[BSAVE]], [[BLOAD]]
* [[SCREEN (statement)|SCREEN]], [[Scancodes]]{{text|(Example 3)}}
* [[Creating Sprite Masks]] {{text|(for non-box shaped sprites)}}
* [[GET and PUT Demo]]
* [[Bitmaps]] 


{{PageNavigation}}
<