SAVEIMAGE: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
(Initial _SAVEIMAGE documentation)
(Add GIF and ICO info)
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:_SAVEIMAGE}}
{{DISPLAYTITLE:_SAVEIMAGE}}
[[_SAVEIMAGE]] saves the contents of an image or screen page to an image file.
'''_SAVEIMAGE''' saves the contents of an image or screen page to an image file.




{{PageSyntax}}
{{PageSyntax}}
: [[_SAVEIMAGE]] {{Parameter|fileName$}}[, [{{Parameter|imageHandle&]}}][,{{Parameter|requirements$}}]]
: [[_SAVEIMAGE]] {{Parameter|fileName$}}[, {{Parameter|imageHandle&}}][, {{Parameter|requirements$}}]




Line 11: Line 11:
* Optional {{Parameter|imageHandle&}} is a [[LONG]] image handle or a valid screen page number.
* Optional {{Parameter|imageHandle&}} is a [[LONG]] image handle or a valid screen page number.
* Optional {{Parameter|requirements$}} [[STRING]] values can be:
* Optional {{Parameter|requirements$}} [[STRING]] values can be:
** '''PNG''': Saves the image as Portable Network Graphics format if no file extension is specified.
** '''BMP''': Saves the image as Windows Bitmap if no file extension is specified.
** '''QOI''': Saves the image as Quite OK Image format if no file extension is specified.
** '''GIF''': Saves the image as Graphics Interchange Format if no file extension is specified.
** '''BMP''': Saves the image as Windows Bitmap format if no file extension is specified.
** '''HDR''': Saves the image as Radiance HDR if no file extension is specified.
** '''TGA''': Saves the image as Truevision TARGA format if no file extension is specified.
** '''ICO''': Saves the image as Windows Icon if no file extension is specified.
** '''JPG''': Saves the image as Joint Photographic Experts Group format if no file extension is specified.
** '''JPG''': Saves the image as Joint Photographic Experts Group if no file extension is specified.
** '''HDR''': Saves the image as Radiance HDR format if no file extension is specified.
** '''PNG''': Saves the image as Portable Network Graphics if no file extension is specified.
** '''QOI''': Saves the image as Quite OK Image if no file extension is specified.
** '''TGA''': Saves the image as Truevision TARGA if no file extension is specified.




{{PageDescription}}
{{PageDescription}}
* {{Parameter|fileName$}} extension name takes precedence over {{Parameter|requirements$}}
* {{Parameter|fileName$}} extension name takes precedence over {{Parameter|requirements$}}
* If no file extension or not format is specified in {{Parameter|requirements$}}, then the PNG format is used by default.
* If no file extension is specified in {{Parameter|fileName$}} and no format is specified in {{Parameter|requirements$}}, then the PNG format is used by default.
* If {{Parameter|imageHandle&}} is omitted then the image handle returned by [[_DISPLAY (function)]] is used.
* If {{Parameter|imageHandle&}} is omitted then the image handle returned by [[_DISPLAY (function)]] is used.
* All attempts are made to ensure the image is saved in the best possible quality in 32-bit RGBA format. Alpha channel information is preserved wherever the format allows.
* Efforts are made to save the image in the highest quality possible using 32-bit RGBA format, ensuring that alpha channel information is retained whenever the format permits.
* SCREEN 0 (text mode) screen and "images" can also be saved. Text surfaces are internally rendered using the master QB64-PE VGA fonts before saving.
* Due to the inherent limitations of GIFs, these images are stored in an 8-bit indexed format, which results in a reduction of quality and color detail.
* Windows ICO files utilize the PNG specification, which enables the storage of images exceeding 256x256 pixels in size.
* SCREEN 0 (text mode) screens and "images" can be saved. Text surfaces are rendered internally using the master QB64-PE VGA fonts prior to saving.
 
 
{{PageAvailability}}
<!-- QB64 = a version or none, QBPE = a version or all, Platforms = yes or no -->
<gallery widths="48px" heights="48px" mode="nolines">
File:Qb64.png|'''none'''
File:Qbpe.png|'''v3.9.0'''
File:Apix.png
File:Win.png|'''yes'''
File:Lnx.png|'''yes'''
File:Osx.png|'''yes'''
</gallery>
<!-- Additional availability notes go below the gallery -->
* ICO and GIF support was added in '''QB64-PE v3.14.0'''.




{{PageExamples}}
{{PageExamples}}
''Example 1:'' Using [[_SAVEIMAGE]] with [[SCREEN]] 0.
;Example 1:It's possible to use '''_SAVEIMAGE''' with text screens.
:This demo draws a Mandelbrot in [[SCREEN]] 0 and then saves the screen as a .jpg image.
{{CodeStart}}
{{CodeStart}}
{{Cl|OPTION}} {{Cl|_EXPLICIT}}
{{Cl|OPTION}} {{Cl|_EXPLICIT}}
Line 37: Line 56:
{{Cl|CONST}} Y_MAX = {{Text|1!|#F580B1}}
{{Cl|CONST}} Y_MAX = {{Text|1!|#F580B1}}
{{Cl|CONST}} MAX_ITER = {{Text|100|#F580B1}}
{{Cl|CONST}} MAX_ITER = {{Text|100|#F580B1}}
{{Cl|CONST}} PIX_CHAR = {{Text|177|#F580B1}}
{{Cl|CONST}} PIX_CHAR = {{Text|48|#F580B1}}


{{Cl|SCREEN}} {{Text|0|#F580B1}}
{{Cl|SCREEN}} {{Text|0|#F580B1}}
Line 74: Line 93:
{{Cl|END}}
{{Cl|END}}
{{CodeEnd}}
{{CodeEnd}}
: ''Explanation:'' Draws a Mandelbrot in [[SCREEN]] 0 and then saves the screen as a .jpg image


----


''Example 2:'' Saving a graphics image to a .png file using [[_SAVEIMAGE]].
;Example 2:Saving a graphics image to a .png file. This is much like example one. However, it renders the graphics to an 8-bit offscreen image and then passes the image handle to '''_SAVEIMAGE'''.
{{CodeStart}}
{{CodeStart}}
{{Cl|OPTION}} {{Cl|_EXPLICIT}}
{{Cl|OPTION}} {{Cl|_EXPLICIT}}
Line 104: Line 123:
         {{Cl|DIM}} i {{Cl|AS}} {{Cl|LONG}}: i = {{Text|0|#F580B1}}
         {{Cl|DIM}} i {{Cl|AS}} {{Cl|LONG}}: i = {{Text|0|#F580B1}}


         {{Cl|DO...LOOP|DO UNTIL}} zx * zx + zy * zy >= {{Text|4|#F580B1}} {{Cl|OR (Boolean)|OR}} i >= MAX_ITER
         {{Cl|DO...LOOP|DO UNTIL}} zx * zx + zy * zy >= {{Text|4|#F580B1}} {{Cl|OR (boolean)|OR}} i >= MAX_ITER
             {{Cl|DIM}} temp {{Cl|AS}} {{Cl|SINGLE}}: temp = zx * zx - zy * zy + cx
             {{Cl|DIM}} temp {{Cl|AS}} {{Cl|SINGLE}}: temp = zx * zx - zy * zy + cx
             zy = {{Text|2|#F580B1}} * zx * zy + cy
             zy = {{Text|2|#F580B1}} * zx * zy + cy
Line 122: Line 141:
{{Cl|END}}
{{Cl|END}}
{{CodeEnd}}
{{CodeEnd}}
: ''Explanation:'' This is like example one. However, it renders the graphics to an 8-bit offscreen image and then passes the image handle to [[_SAVEIMAGE]].




{{PageSeeAlso}}
{{PageSeeAlso}}
* [https://qb64phoenix.com/forum/showthread.php?tid=2749 Featured in our "Keyword of the Day" series]
* [[_LOADIMAGE]], [[_ICON]], [[$EXEICON]]
* [[_LOADIMAGE]], [[_ICON]], [[$EXEICON]]
* [[SCREEN]]
* [[SCREEN]]

Latest revision as of 17:23, 21 July 2024

_SAVEIMAGE saves the contents of an image or screen page to an image file.


Syntax

_SAVEIMAGE fileName$[, imageHandle&][, requirements$]


Parameters

  • fileName$ is literal or variable STRING file name value.
  • Optional imageHandle& is a LONG image handle or a valid screen page number.
  • Optional requirements$ STRING values can be:
    • BMP: Saves the image as Windows Bitmap if no file extension is specified.
    • GIF: Saves the image as Graphics Interchange Format if no file extension is specified.
    • HDR: Saves the image as Radiance HDR if no file extension is specified.
    • ICO: Saves the image as Windows Icon if no file extension is specified.
    • JPG: Saves the image as Joint Photographic Experts Group if no file extension is specified.
    • PNG: Saves the image as Portable Network Graphics if no file extension is specified.
    • QOI: Saves the image as Quite OK Image if no file extension is specified.
    • TGA: Saves the image as Truevision TARGA if no file extension is specified.


Description

  • fileName$ extension name takes precedence over requirements$
  • If no file extension is specified in fileName$ and no format is specified in requirements$, then the PNG format is used by default.
  • If imageHandle& is omitted then the image handle returned by _DISPLAY (function) is used.
  • Efforts are made to save the image in the highest quality possible using 32-bit RGBA format, ensuring that alpha channel information is retained whenever the format permits.
  • Due to the inherent limitations of GIFs, these images are stored in an 8-bit indexed format, which results in a reduction of quality and color detail.
  • Windows ICO files utilize the PNG specification, which enables the storage of images exceeding 256x256 pixels in size.
  • SCREEN 0 (text mode) screens and "images" can be saved. Text surfaces are rendered internally using the master QB64-PE VGA fonts prior to saving.


Availability

  • none

    none

  • v3.9.0

    v3.9.0

  • Apix.png
  • yes

    yes

  • yes

    yes

  • yes

    yes

  • ICO and GIF support was added in QB64-PE v3.14.0.


Examples

Example 1
It's possible to use _SAVEIMAGE with text screens.
This demo draws a Mandelbrot in SCREEN 0 and then saves the screen as a .jpg image.
OPTION _EXPLICIT

CONST X_MIN = -2!
CONST X_MAX = 1!
CONST Y_MIN = -1!
CONST Y_MAX = 1!
CONST MAX_ITER = 100
CONST PIX_CHAR = 48

SCREEN 0
WIDTH 160, 100
_FONT 8

DIM w AS LONG: w = _WIDTH
DIM h AS LONG: h = _HEIGHT
DIM maxX AS LONG: maxX = w - 1
DIM maxY AS LONG: maxY = h - 1

DIM y AS LONG: FOR y = 0 TO maxY
    DIM x AS LONG: FOR x = 0 TO maxX
        DIM cx AS SINGLE: cx = X_MIN + (x / w) * (X_MAX - X_MIN)
        DIM cy AS SINGLE: cy = Y_MIN + (y / h) * (Y_MAX - Y_MIN)

        DIM zx AS SINGLE: zx = 0
        DIM zy AS SINGLE: zy = 0
        DIM i AS LONG: i = 0

        DO UNTIL zx * zx + zy * zy >= 4 OR i >= MAX_ITER
            DIM temp AS SINGLE: temp = zx * zx - zy * zy + cx
            zy = 2 * zx * zy + cy
            zx = temp
            i = i + 1
        LOOP

        COLOR i MOD 16

        _PRINTSTRING (x + 1, y + 1), CHR$(PIX_CHAR)
    NEXT x
NEXT y

_SAVEIMAGE "TextMandelbrot!.jpg"

END
Example 2
Saving a graphics image to a .png file. This is much like example one. However, it renders the graphics to an 8-bit offscreen image and then passes the image handle to _SAVEIMAGE.
OPTION _EXPLICIT

CONST X_MIN = -2!
CONST X_MAX = 1!
CONST Y_MIN = -1!
CONST Y_MAX = 1!
CONST MAX_ITER = 100

DIM img AS LONG: img = _NEWIMAGE(640 * 2, 400 * 2, 256)
_DEST img

DIM w AS LONG: w = _WIDTH
DIM h AS LONG: h = _HEIGHT
DIM maxX AS LONG: maxX = w - 1
DIM maxY AS LONG: maxY = h - 1

DIM y AS LONG: FOR y = 0 TO maxY
    DIM x AS LONG: FOR x = 0 TO maxX
        DIM cx AS SINGLE: cx = X_MIN + (x / maxX) * (X_MAX - X_MIN)
        DIM cy AS SINGLE: cy = Y_MIN + (y / maxY) * (Y_MAX - Y_MIN)

        DIM zx AS SINGLE: zx = 0
        DIM zy AS SINGLE: zy = 0
        DIM i AS LONG: i = 0

        DO UNTIL zx * zx + zy * zy >= 4 OR i >= MAX_ITER
            DIM temp AS SINGLE: temp = zx * zx - zy * zy + cx
            zy = 2 * zx * zy + cy
            zx = temp
            i = i + 1
        LOOP

        PSET (x, y), (i MOD 16) * 16 + (i MOD 8)
    NEXT x
NEXT y

_SAVEIMAGE "Mandelbrot", img

_DEST 0
PRINT "Saved image."

END


See also

Retrieved from "https://qb64phoenix.com/qb64wiki/index.php?title=SAVEIMAGE&oldid=9051"