COPYIMAGE: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
m (Protected "COPYIMAGE" ([Edit=Allow only autoconfirmed users] (indefinite) [Move=Allow only autoconfirmed users] (indefinite)))
No edit summary
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{DISPLAYTITLE:_COPYIMAGE}}
{{DISPLAYTITLE:_COPYIMAGE}}
The [[_COPYIMAGE]] function creates an identical designated image in memory with a different negative [[LONG]] handle value.
This function creates an identical designated image in memory with a different negative [[LONG]] handle value.




{{PageSyntax}}
{{PageSyntax}}
: newhandle& = [[_COPYIMAGE]][({{Parameter|imageHandle&}}[, {{Parameter|mode%}})]]
: newhandle& = [[_COPYIMAGE]]({{Parameter|imageHandle&}}[, {{Parameter|mode%}}])




{{Parameters}}
{{PageParameters}}
* The [[LONG]] ''newhandle&'' value returned will be different than the source handle value supplied.
* The [[LONG]] ''newhandle&'' value returned will be different than the source handle value supplied.
* If ''imageHandle&'' parameter is omitted or zero is designated, the current software [[_DEST|destination]] screen or image is copied.
* If ''imageHandle&'' is designated being zero, the current software [[_DEST|destination]] screen or image is copied.
* If 1 is designated instead of an ''imageHandle&'', it designates the last OpenGL hardware surface to copy.
* If 1 is designated instead of an ''imageHandle&'', it designates the last OpenGL hardware surface to copy.
* ''Mode'' 32 can be used to convert 256 color images to 32 bit colors.
* ''Mode'' 32 can be used to convert 256 color images to 32 bit colors.
Line 21: Line 21:
* '''32 bit screen surface backgrounds (black) have zero [[_ALPHA]] so that they are transparent when placed over other surfaces.'''
* '''32 bit screen surface backgrounds (black) have zero [[_ALPHA]] so that they are transparent when placed over other surfaces.'''
: Use [[CLS]] or [[_DONTBLEND]] to make a new surface background [[_ALPHA]] 255 or opaque.
: Use [[CLS]] or [[_DONTBLEND]] to make a new surface background [[_ALPHA]] 255 or opaque.
* '''Images are not deallocated when the [[SUB]] or [[FUNCTION]] they are created in ends. Free them with [[_FREEIMAGE]].'''
* '''Images are not deallocated when the [[SUB]] or [[FUNCTION]] they are created in ends. Free them with [[_FREEIMAGE]].'''
* '''It is important to free discarded images with [[_FREEIMAGE]] to prevent PC memory allocation errors!'''
* '''It is important to free discarded images with [[_FREEIMAGE]] to prevent PC memory allocation errors!'''
* '''Do not try to free image handles currently being used as the active [[SCREEN]]. Change screen modes first.'''
* '''Do not try to free image handles currently being used as the active [[SCREEN]]. Change screen modes first.'''
Line 27: Line 27:


{{PageExamples}}
{{PageExamples}}
''Example:'' Restoring a Legacy SCREEN using the _COPYIMAGE return value.
;Example 1:Restoring a Legacy SCREEN using the _COPYIMAGE return value.
{{CodeStart}}'' ''
{{CodeStart}}
{{Cl|SCREEN}} {{Text|13|#F580B1}}
{{Cl|CIRCLE}} ({{Text|160|#F580B1}}, {{Text|100|#F580B1}}), {{Text|100|#F580B1}}, {{Text|40|#F580B1}}
{{Cl|DO}}: {{Cl|SLEEP}}: {{Cl|DO...LOOP|LOOP UNTIL}} {{Cl|INKEY$}} <> {{Text|<nowiki>""</nowiki>|#FFB100}}


{{Cl|SCREEN}} 13
{{Text|<nowiki>'backup screen before changing SCREEN mode</nowiki>|#919191}}
{{Cl|CIRCLE}} (160, 100), 100, 40
oldmode& = {{Cl|_COPYIMAGE}}({{Text|0|#F580B1}}) {{Text|<nowiki>'the 0 value designates the current destination SCREEN</nowiki>|#919191}}
DO: {{Cl|SLEEP}}: {{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|INKEY$}} <> ""


'backup screen before changing {{Cl|SCREEN}} mode
s& = {{Cl|_NEWIMAGE}}({{Text|800|#F580B1}}, {{Text|600|#F580B1}}, {{Text|32|#F580B1}})
oldmode& = {{Cl|_COPYIMAGE}}(0)  'the 0 value designates the current destination {{Cl|SCREEN}}
 
s& = {{Cl|_NEWIMAGE}}(800, 600, 32)
{{Cl|SCREEN}} s&
{{Cl|SCREEN}} s&
{{Cl|LINE}} (100, 100)-(500, 500), {{Cl|_RGB}}(0, 255, 255), BF
{{Cl|LINE}} ({{Text|100|#F580B1}}, {{Text|100|#F580B1}})-({{Text|500|#F580B1}}, {{Text|500|#F580B1}}), {{Cl|_RGB}}({{Text|0|#F580B1}}, {{Text|255|#F580B1}}, {{Text|255|#F580B1}}), BF
DO: {{Cl|SLEEP}}: {{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|INKEY$}} <> ""
{{Cl|DO}}: {{Cl|SLEEP}}: {{Cl|DO...LOOP|LOOP UNTIL}} {{Cl|INKEY$}} <> {{Text|<nowiki>""</nowiki>|#FFB100}}


{{Cl|SCREEN}} oldmode&       'restore original screen
{{Cl|SCREEN}} oldmode& {{Text|<nowiki>'restore original screen</nowiki>|#919191}}
{{Cl|IF...THEN|IF}} s& < -1 THEN {{Cl|_FREEIMAGE}} s&
{{Cl|IF}} s& < {{Text|-1|#F580B1}} {{Cl|THEN}} {{Cl|_FREEIMAGE}} s&
{{Cl|END}} '' ''
{{Cl|END}}
{{CodeEnd}}
{{CodeEnd}}
: ''Note:'' Only free valid handle values with [[_FREEIMAGE]] AFTER a new [[SCREEN]] mode is being used by the program.
{{Small|Code courtesy of Galleon}}
;Note:Only free valid handle values with [[_FREEIMAGE]] AFTER a new [[SCREEN]] mode is being used by the program.


----


''Example 2:'' Program that copies desktop to a hardware image to form a 3D triangle ('''version 1.000 and up'''):
;Example 2:Program that copies desktop to a hardware image to form a 3D triangle ('''version 1.000 and up'''):
{{CodeStart}} '' ''
{{CodeStart}}
{{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(640, 480, 32)
{{Cl|SCREEN}} {{Cl|_NEWIMAGE}}({{Text|640|#F580B1}}, {{Text|480|#F580B1}}, {{Text|32|#F580B1}})
my_hardware_handle = {{Cl|_COPYIMAGE}}({{Cl|_SCREENIMAGE}}, 33) 'take a screenshot and use it as our texture
my_hardware_handle = {{Cl|_COPYIMAGE}}({{Cl|_SCREENIMAGE}}, {{Text|33|#F580B1}}) {{Text|<nowiki>'take a screenshot and use it as our texture</nowiki>|#919191}}
{{Cl|_MAPTRIANGLE}} (0, 0)-(500, 0)-(250, 500), my_hardware_handle TO_
{{Cl|_MAPTRIANGLE}} ({{Text|0|#F580B1}}, {{Text|0|#F580B1}})-({{Text|500|#F580B1}}, {{Text|0|#F580B1}})-({{Text|250|#F580B1}}, {{Text|500|#F580B1}}), my_hardware_handle {{Cl|TO}} _
(-1, 0, -1)-(1, 0, -1)-(0, 5, -10), , _SMOOTH
({{Text|-1|#F580B1}}, {{Text|0|#F580B1}}, {{Text|-1|#F580B1}})-({{Text|1|#F580B1}}, {{Text|0|#F580B1}}, {{Text|-1|#F580B1}})-({{Text|0|#F580B1}}, {{Text|5|#F580B1}}, {{Text|-10|#F580B1}}), , {{Cl|_SMOOTH (function)|_SMOOTH}}
{{Cl|_DISPLAY}}
{{Cl|_DISPLAY}}
{{Cl|DO...LOOP|DO}}: {{Cl|_LIMIT}} 30: {{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|INKEY$}} <> "" '' ''
{{Cl|DO}}: {{Cl|_LIMIT}} {{Text|30|#F580B1}}: {{Cl|DO...LOOP|LOOP UNTIL}} {{Cl|INKEY$}} <> {{Text|<nowiki>""</nowiki>|#FFB100}}
{{CodeEnd}}{{small|Code courtesy of Galleon}}
{{CodeEnd}}
{{Small|Code courtesy of Galleon}}




{{PageSeeAlso}}
{{PageSeeAlso}}
* [[_LOADIMAGE]], [[_NEWIMAGE]]
* [[_LOADIMAGE]], [[_NEWIMAGE]], [[_SAVEIMAGE]]
* [[_PUTIMAGE]], [[_MAPTRIANGLE]]
* [[_PUTIMAGE]], [[_MAPTRIANGLE]]
* [[_SOURCE]], [[_DEST]]
* [[_SOURCE]], [[_DEST]]
* [[_FREEIMAGE]]
* [[_FREEIMAGE]]
* [[_FILELIST$ (function)]] {{text|(Demo of _COPYIMAGE)}}
* [[_FILELIST$ (function)]] {{Text|(Demo of _COPYIMAGE)}}
* [[_DISPLAYORDER]]
* [[_DISPLAYORDER]]
* [[Hardware images]]
* [[Hardware images]]

Latest revision as of 08:20, 10 January 2024

This function creates an identical designated image in memory with a different negative LONG handle value.


Syntax

newhandle& = _COPYIMAGE(imageHandle&[, mode%])


Parameters

  • The LONG newhandle& value returned will be different than the source handle value supplied.
  • If imageHandle& is designated being zero, the current software destination screen or image is copied.
  • If 1 is designated instead of an imageHandle&, it designates the last OpenGL hardware surface to copy.
  • Mode 32 can be used to convert 256 color images to 32 bit colors.
  • Mode 33 images are hardware accelerated in version 1.000 and up, and are created using _LOADIMAGE or _COPYIMAGE.


Description

  • The function copies any image or screen handle to a new and unique negative LONG handle value.
  • Valid copy handles are less than -1. Invalid handles return -1 or 0 if it was never created.
  • Every attribute of the passed image or program screen is copied to a new handle value in memory.
  • 32 bit screen surface backgrounds (black) have zero _ALPHA so that they are transparent when placed over other surfaces.
Use CLS or _DONTBLEND to make a new surface background _ALPHA 255 or opaque.
  • Images are not deallocated when the SUB or FUNCTION they are created in ends. Free them with _FREEIMAGE.
  • It is important to free discarded images with _FREEIMAGE to prevent PC memory allocation errors!
  • Do not try to free image handles currently being used as the active SCREEN. Change screen modes first.


Examples

Example 1
Restoring a Legacy SCREEN using the _COPYIMAGE return value.
SCREEN 13
CIRCLE (160, 100), 100, 40
DO: SLEEP: LOOP UNTIL INKEY$ <> ""

'backup screen before changing SCREEN mode
oldmode& = _COPYIMAGE(0) 'the 0 value designates the current destination SCREEN

s& = _NEWIMAGE(800, 600, 32)
SCREEN s&
LINE (100, 100)-(500, 500), _RGB(0, 255, 255), BF
DO: SLEEP: LOOP UNTIL INKEY$ <> ""

SCREEN oldmode& 'restore original screen
IF s& < -1 THEN _FREEIMAGE s&
END
Code courtesy of Galleon
Note
Only free valid handle values with _FREEIMAGE AFTER a new SCREEN mode is being used by the program.
Example 2
Program that copies desktop to a hardware image to form a 3D triangle (version 1.000 and up):
SCREEN _NEWIMAGE(640, 480, 32)
my_hardware_handle = _COPYIMAGE(_SCREENIMAGE, 33) 'take a screenshot and use it as our texture
_MAPTRIANGLE (0, 0)-(500, 0)-(250, 500), my_hardware_handle TO _
(-1, 0, -1)-(1, 0, -1)-(0, 5, -10), , _SMOOTH
_DISPLAY
DO: _LIMIT 30: LOOP UNTIL INKEY$ <> ""
Code courtesy of Galleon


See also


Navigation:
Main Page with Articles and Tutorials
Keyword Reference - Alphabetical
Keyword Reference - By usage
Report a broken link
Retrieved from "https://qb64phoenix.com/qb64wiki/index.php?title=COPYIMAGE&oldid=8683"