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") '[http://www.qb64.net/forum/index.php QB64 bee image from Forum] 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}}