mirror of
https://github.com/QB64Official/qb64.git
synced 2024-08-30 11:50:16 +00:00
90 lines
6 KiB
Text
90 lines
6 KiB
Text
|
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}}
|