Moving ever backwards in our list of "new" QB64PE-releases, we count down to v3.10 and the following two commands which work together:
https://qb64phoenix.com/qb64wiki/index.php/$EMBED
https://qb64phoenix.com/qb64wiki/index.php/EMBEDDED$
Now let me say two very important things about these commands:
1) These are probably in my top 10 of new commands, and are some of the most useful commands we've ever added into the language.
2) These are utterly useless commands for many people, in most use cases.
Now take a moment to let those two statements sink in. In fact, go back and reread them once again. And then ask yourselves, "Whuuttt?? Is Steve drunk again??"
No. Steve is not drunk. Steve meant exactly what he wrote above.
Now, let me explain why I feel this way with these commands.
First, folks need to understand what the purpose of $EMBED and _EMBEDDED$ are, for their programs -- and that purpose is to embed files/data/resources into the compiled EXE.
EMBED STUFF INTO THE EXE!!!! <-- Let's be certain to highlight this point.
And it's this whole highlighted point that makes me say that this is one of the most useful features/keywords to be added to the language in a long time. Lots of folks have worked on ways to embed data into their programs, such as Dav's BASFILE routines.
Now, let's take a moment and step sideways here and talk about @Dav 's little BASFILE routine. What's it do for us exactly, and how would one make use of it?
Dav's routine takes a resource and turns it into DATA statements, which you then paste directly into your code. There's then a routine which converts those DATA statements back into the given resource (such as a font file, image, or sound file), which you can use in your program. The original resource doesn't have to be anywhere on your drive, or exist at all, once those DATA statements are pasted into the source -- they're 100% embedded into the BAS file itself.
And that's useful as heck!! Convert a file, paste the contents into your source, and then you can share it via the forums or wherever and not have to worry about including any additional files for folks to download.
@Dav -- You rock, man!! (And not just cause you're a musician and litterly rock either! )
But... there's a slight problem with Dav's method of doing things -- and that's simple CODE BLOAT. Embed a couple of large fonts. Then embed a couple of large sound files. Add in a large image file or three. Suddenly you've got 300,000 lines of DATA statements to navigate past and work around and to TRY and share wherever you want to share them. The IDE is going to get laggy and bog down trying to process all those lines. The forums is going to stick out its tongue and say, "Nuh uh! You've exceeded the limit for any post!" Notice that even in the title, Dav mentions: "Converts small files to BAS code."
Large files are going to run into all sorts of issues over time with such a method...
...So that's NOT how QB64PE does things with $EMBED and _EMBEDDED$!!
Take a moment to understand Dav's process, and then take a moment to learn how QB64PE does things:
QB64PE lets you type in a single line to embed data into the EXE:
As per our wiki example, you can see the two $EMBED statements above -- both are referring to EXTERNAL data files. "source\peLogo.png" and "source\qb4pe.png"...
... and this is why I say $EMBED is utterly useless for 99.98765% of most people and use cases.
Folks normally tend to include their source files with any EXE files which they distribute via the forums, or github, or other means. QB4PE compiled EXEs are small, unregistered EXE files, and as such, will likely trigger various antivirus warnings for folks. The way to bypass that suspicion that an EXE might be malicious or corrupted, is simply to share the BAS file and source, and then let folks compile it themselves.
Add allowing folks to compile for themselves has the added bonus of making the program cross-platform independent in most cases. A guy on Linux can compile it to run on his version of Linux. Someone with a Raspberry Pi can compile it to run on his Pi. Windows folks can compile the source to run on Windows...
And if you're going to share the source files, you STILL HAVE TO SHARE THOSE RESOURCE FILES!!!
QB64PE pulls from those external resource files, and embeds them into the EXE at compile time. Without them, folks aren't going to be able to access the data and compile the program properly.
$EMBED and _$MBEDDED$ require that the resources exist, be findable, and be available at compile time -- unlike Dav's method which converts those resources and embeds them directly into the source BAS file itself.
And thus, my statement that $EMBED is going to be worthless for most folks, in most use cases.
IF you're going to be sharing the BAS source, and you want others to be able to build the EXE for themselves, then there's not much point to $EMBED. Just pull in the external resource with _LoadFont, _SndLoad, _LoadFont, or whatever other command you need. There's no real reason to bloat the EXE by cramming that file into it, while also having that file sitting in a folder right there beside the EXE!
The only real time where one wants to use $EMBED and _EMBEDDED$ is when they're wanting to embed data into the EXE, *and NOT share the source with that EXE*!
And, in that instance, $EMBED and _EMBEDDED$ are absolutely 100%-certified gold commands!!
Now, I know I haven't went over how to use these commands much here, but that's simply because @RhoSigma made their usage so simple for us. The wiki covers usage quite well, and I don't think there's too much I can offer for folks over the simple example below:
$EMBED <the reource to be embedded into your program> , <a handle to distinguish it for later use>
then later.... _EMBEDDED$("<the handle you used to distinguish that file>")
The first designates the file to embed into the QB64PE program.
The second assigns the contents of that file to a string, which you can then do whatever you need to do with it.
They're simple as heck to use. The trick is knowing IF using them is going to help you do what you're trying to do in the long run, or not.
If you're looking to embed the resource into the EXE so you can distribute it as a stand-alone program, then, "YES!! YOU WANT TO USE THEM!!"
If you're going to share the BAS source and let folks compile the program for themselves, so you can be platform-independent and such, then you might want to rethink using $EMBED. You'll still need to share the resource files so folks can embed that external data into their compiled EXE. Why not just use that external data directly and skip packing a second copy of that resource into the EXE when it's right there beside it with the BAS file??
Something to think about for folks, I hope.
https://qb64phoenix.com/qb64wiki/index.php/$EMBED
https://qb64phoenix.com/qb64wiki/index.php/EMBEDDED$
Now let me say two very important things about these commands:
1) These are probably in my top 10 of new commands, and are some of the most useful commands we've ever added into the language.
2) These are utterly useless commands for many people, in most use cases.
Now take a moment to let those two statements sink in. In fact, go back and reread them once again. And then ask yourselves, "Whuuttt?? Is Steve drunk again??"
No. Steve is not drunk. Steve meant exactly what he wrote above.
Now, let me explain why I feel this way with these commands.
First, folks need to understand what the purpose of $EMBED and _EMBEDDED$ are, for their programs -- and that purpose is to embed files/data/resources into the compiled EXE.
EMBED STUFF INTO THE EXE!!!! <-- Let's be certain to highlight this point.
And it's this whole highlighted point that makes me say that this is one of the most useful features/keywords to be added to the language in a long time. Lots of folks have worked on ways to embed data into their programs, such as Dav's BASFILE routines.
Now, let's take a moment and step sideways here and talk about @Dav 's little BASFILE routine. What's it do for us exactly, and how would one make use of it?
Dav's routine takes a resource and turns it into DATA statements, which you then paste directly into your code. There's then a routine which converts those DATA statements back into the given resource (such as a font file, image, or sound file), which you can use in your program. The original resource doesn't have to be anywhere on your drive, or exist at all, once those DATA statements are pasted into the source -- they're 100% embedded into the BAS file itself.
And that's useful as heck!! Convert a file, paste the contents into your source, and then you can share it via the forums or wherever and not have to worry about including any additional files for folks to download.
@Dav -- You rock, man!! (And not just cause you're a musician and litterly rock either!
)But... there's a slight problem with Dav's method of doing things -- and that's simple CODE BLOAT. Embed a couple of large fonts. Then embed a couple of large sound files. Add in a large image file or three. Suddenly you've got 300,000 lines of DATA statements to navigate past and work around and to TRY and share wherever you want to share them. The IDE is going to get laggy and bog down trying to process all those lines. The forums is going to stick out its tongue and say, "Nuh uh! You've exceeded the limit for any post!" Notice that even in the title, Dav mentions: "Converts small files to BAS code."
Large files are going to run into all sorts of issues over time with such a method...
...So that's NOT how QB64PE does things with $EMBED and _EMBEDDED$!!
Take a moment to understand Dav's process, and then take a moment to learn how QB64PE does things:
QB64PE lets you type in a single line to embed data into the EXE:
Code: (Select All)
$EMBED:'source\peLogo.png','bigImg'
$EMBED:'source\qb64pe.png','smallImg'
SCREEN _NEWIMAGE(640, 480, 32)
bi& = _LOADIMAGE(_EMBEDDED$("bigImg"), 32, "memory")
si& = _LOADIMAGE(_EMBEDDED$("smallImg"), 32, "memory")
_PUTIMAGE (140, 180), bi&
_PUTIMAGE (410, 230), si&
_FREEIMAGE si&
_FREEIMAGE bi&
ENDAs per our wiki example, you can see the two $EMBED statements above -- both are referring to EXTERNAL data files. "source\peLogo.png" and "source\qb4pe.png"...
... and this is why I say $EMBED is utterly useless for 99.98765% of most people and use cases.
Folks normally tend to include their source files with any EXE files which they distribute via the forums, or github, or other means. QB4PE compiled EXEs are small, unregistered EXE files, and as such, will likely trigger various antivirus warnings for folks. The way to bypass that suspicion that an EXE might be malicious or corrupted, is simply to share the BAS file and source, and then let folks compile it themselves.
Add allowing folks to compile for themselves has the added bonus of making the program cross-platform independent in most cases. A guy on Linux can compile it to run on his version of Linux. Someone with a Raspberry Pi can compile it to run on his Pi. Windows folks can compile the source to run on Windows...
And if you're going to share the source files, you STILL HAVE TO SHARE THOSE RESOURCE FILES!!!
QB64PE pulls from those external resource files, and embeds them into the EXE at compile time. Without them, folks aren't going to be able to access the data and compile the program properly.
$EMBED and _$MBEDDED$ require that the resources exist, be findable, and be available at compile time -- unlike Dav's method which converts those resources and embeds them directly into the source BAS file itself.
And thus, my statement that $EMBED is going to be worthless for most folks, in most use cases.
IF you're going to be sharing the BAS source, and you want others to be able to build the EXE for themselves, then there's not much point to $EMBED. Just pull in the external resource with _LoadFont, _SndLoad, _LoadFont, or whatever other command you need. There's no real reason to bloat the EXE by cramming that file into it, while also having that file sitting in a folder right there beside the EXE!
The only real time where one wants to use $EMBED and _EMBEDDED$ is when they're wanting to embed data into the EXE, *and NOT share the source with that EXE*!
And, in that instance, $EMBED and _EMBEDDED$ are absolutely 100%-certified gold commands!!
Now, I know I haven't went over how to use these commands much here, but that's simply because @RhoSigma made their usage so simple for us. The wiki covers usage quite well, and I don't think there's too much I can offer for folks over the simple example below:
Code: (Select All)
$EMBED:'source\peLogo.png','bigImg'
$EMBED:'source\qb64pe.png','smallImg'
SCREEN _NEWIMAGE(640, 480, 32)
bi& = _LOADIMAGE(_EMBEDDED$("bigImg"), 32, "memory")
si& = _LOADIMAGE(_EMBEDDED$("smallImg"), 32, "memory")
_PUTIMAGE (140, 180), bi&
_PUTIMAGE (410, 230), si&$EMBED <the reource to be embedded into your program> , <a handle to distinguish it for later use>
then later.... _EMBEDDED$("<the handle you used to distinguish that file>")
The first designates the file to embed into the QB64PE program.
The second assigns the contents of that file to a string, which you can then do whatever you need to do with it.
They're simple as heck to use. The trick is knowing IF using them is going to help you do what you're trying to do in the long run, or not.
If you're looking to embed the resource into the EXE so you can distribute it as a stand-alone program, then, "YES!! YOU WANT TO USE THEM!!"
If you're going to share the BAS source and let folks compile the program for themselves, so you can be platform-independent and such, then you might want to rethink using $EMBED. You'll still need to share the resource files so folks can embed that external data into their compiled EXE. Why not just use that external data directly and skip packing a second copy of that resource into the EXE when it's right there beside it with the BAS file??
Something to think about for folks, I hope.
