QB64 Phoenix Edition
Extended KotD #14: _SAVEIMAGE - Printable Version

+- QB64 Phoenix Edition (https://qb64phoenix.com/forum)
+-- Forum: Official Links (https://qb64phoenix.com/forum/forumdisplay.php?fid=16)
+--- Forum: Learning Resources and Archives (https://qb64phoenix.com/forum/forumdisplay.php?fid=13)
+---- Forum: Keyword of the Day! (https://qb64phoenix.com/forum/forumdisplay.php?fid=49)
+---- Thread: Extended KotD #14: _SAVEIMAGE (/showthread.php?tid=2749)

Extended KotD #14: _SAVEIMAGE - SMcNeill - 05-29-2024

Ah, _SaveImage, my old friend!  How I loves you.  How I hates you.  How your existance makes me want to wax profane like Shakespeare!   "Why then, O brawling love! O loving hate! O any thing, of nothing first create! O heavy lightness, serious vanity, Misshapen chaos of well-seeming forms, Feather of lead, bright smoke, cold fire, sick health, Still-waking sleep, that is not what it is! This love feel I, that feel no love in this."

For ages and ages and ages, poor ole Steve worked hard to write and maintain a SaveImage Library for use with QB64 and QB64PE.  https://qb64phoenix.com/forum/showthread.php?tid=20 <-- This library has been around forever and ever and ever, and poor ole Steve poured a lot of sweat and blood and tears and late nights fixing a nice library which works in QB64, in all screen modes (including text screens), to allow the user to save those screens (full or partial) in various image formats.  I poured over GIF, BMP, PNG, JPG format specifications, sorted them out to the point where I could faithfully create them, and then I wrote simple code so an end-user could just do something like the following to save those screens:

SaveImage "My Screenshot.bmp"

And then...  all in one night...  back in version 3.9....  that all became obsolete!!

WAAAHHHHHHHH!!!

(And it doesn't even matter that I was the one who asked about it and helped get things going for the new command to be added to the core language. Tongue )


Back in v3.9, _SaveImage (wiki entry) was released, and it did everything that my library did (mostly) -- and then some! 

Whereas my old library allows the user to save images in GIF, BMP, PNG, JPG formats, the new _SaveImage command allows users to quickly and easily save the screen in any of the following formats:
  • PNG: Saves the image as Portable Network Graphics format if no file extension is specified.
  • QOI: Saves the image as Quite OK Image format if no file extension is specified.
  • BMP: Saves the image as Windows Bitmap format if no file extension is specified.
  • TGA: Saves the image as Truevision TARGA format if no file extension is specified.
  • JPG: Saves the image as Joint Photographic Experts Group format if no file extension is specified.
  • HDR: Saves the image as Radiance HDR format if no file extension is specified.
Now, if you notice, all of these wiki entries have "if no file extension is specified" attached to the end of them.  From talking to various folks, it appears that these extra few words are the main thing that confuse people in the wiki explaination of how to use this command.  (Any suggestions for how to clarify things better, can always be submitted for Rho to take a look at, if anyone has any brilliant insight to word this better.)

Basically, the way _SaveImage works is very simple, with 3 possible parameters to it:

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

(Note that the last two parameters for imageHandle& and requirements$ are inside brackets and are thus optional parameters.)

The way these break down for us is rather simple.

_SaveImage  <-- the command name.  Always got to have a command name before any parameters!
fileName$    <-- the name that we to save the image to, on our storage device.  
imageHandle&     <-- this is the handle to the image that we want to save, in case it's not our current _DISPLAY
requirements$      <--- *THIS* is what that "if no file extension is specified" is refering to.

fileName$ is NOT optional, as you can't save a file with no name.  Big Grin

fileName$ also takes precidence in how we save our file, IF YOU SPECIFY A VALID EXTENSION.   For examples:

_SaveImage "foo.BMP"    <-- This will create a BMP file, of the current _Display image.
_SaveImage "foo.BMP", WorkScreen     <-- This will create a BMP file, of whatever image is associated with the WorkScreen handle.
_SaveImage "foo.BMP",  , "JPG"          <-- This will create a BMP file, of the current _Display image.  This will ignore that last paramater as the file type is specified in the name (foo.BMP).   (Notice I left that middle parameter blank, as it's optional.)
_SaveImage "foo",  , "JPG"          <-- This will create a JPG file, of the current _Display image.  Notice that the filename doesn't have any extension associated with it?

It's only when the filename has no extension that we use the 3rd parameter.  After all, how silly would it be to have "PNG" files saved under the name "foo.QOI"??


And with that one clarification out of the way, there's really not much else to say about it.   This is one of our simplest commands to learn, use, and master, in my opinion.

_SaveImage "My Screenshot.BMP"    <-- 99.99% of the time, that's all someone needs to save the screen image.   What can be any simpler than that??

RE: Extended KotD #14: _SaveImage - RhoSigma - 05-29-2024

IMHO the name requirements$ for the 3rd parameter was chosen somewhat unfortunate.

It should better be called defaultformat$, as it does exactly that, it designates the default picture file format for all file names without explicit format specification (to be given by a proper known file extension).

In that case the Wiki text could be streamlined to be less confusing and also it could be better marked as an optional override parameter, which just overrides the default default format PNG.