EMBEDDED$: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
(Created page with "{{DISPLAYTITLE:_EMBEDDED$}} The '''_EMBEDDED$''' function is used to recall the data of a file which was earlier embedded into the EXE file using the $EMBED metacommand. You can roughly compare this to a RESTORE to any DATA block and then using READ to retrieve the data. {{PageSyntax}} : {{Parameter|filedata$}} = _EMBEDDED$("{{Parameter|handle}}") {{PageParameters}} ; IMPORTANT :* The parameter {{Parameter|handle}} must be given as a literal strin...")
 
No edit summary
 
(10 intermediate revisions by the same user not shown)
Line 9: Line 9:
{{PageParameters}}
{{PageParameters}}
; IMPORTANT
; IMPORTANT
:* The parameter {{Parameter|handle}} must be given as a literal string enclosed in quotes, variables cannot be used here.
:* The parameter {{Parameter|handle}} must be given as a {{Text|single literal string|red}} enclosed in quotes, variables cannot be used here.
:* The parameter will be checked while typing to ensure its validity, warnings (if any) will be displayed immediately in the IDE status area.
:* Your inputs are checked while typing to ensure its validity, warnings (if any) will be displayed immediately in the IDE status area.
* The {{Parameter|filedata$}} will receive the embedded file data as a single contiguous string, just as you had regularly [[OPEN]]ed the file and read its entire contents into that string.
* The {{Parameter|filedata$}} will receive the embedded file data as a single contiguous string, just as you would regularly [[OPEN]] the file and read its entire contents into that string.
* The {{Parameter|handle}} is a unique case sensitive identifier beginning with a letter and only containing lower/upper case letters and/or numbers. It must exactly match the {{Parameter|handle}} value used to [[$EMBED]] the respective file.
* The {{Parameter|handle}} is a unique case sensitive identifier beginning with a letter and only containing lower/upper case letters and/or numbers. It must exactly match the {{Parameter|handle}} value used to [[$EMBED]] the respective file.
** You can compare this identifier to the line label in front of a [[DATA]] block, which is later used in a [[RESTORE]] call to set the [[READ]] pointer to exactly that [[DATA]] block.
** You can compare this identifier to the line label in front of a [[DATA]] block, which is later used in a [[RESTORE]] call to set the [[READ]] pointer to exactly that [[DATA]] block.
Line 17: Line 17:


{{PageDescription}}
{{PageDescription}}
* All embedded files can be recalled individually by using its respective {{Parameter|handle}} identifier.
** If required, decompression is done internally, hence you always get back the original file contents.
* Recalling a file multiple times is possible, but in regard for the needed decompression time considered inefficient. Rather recall the file once and store the result in a [[STRING]] variable, if you know you need it multiple times in your program.
* To easily embed a file into your compiled EXE file use the [[$EMBED]] metacommand.
* Embedding files can be useful to deliver a program inclusive all required assets in just one EXE file.
* Embedding files can be useful to deliver a program inclusive all required assets in just one EXE file.
* No more worries whether a user installs your program correctly and retains the required folder structure.
* No more worries whether a user installs your program correctly and retains the required folder structure.
* If required, you can write the files back to disk, i.e. it could serve as an simple installer or package manager.
* If required, you can easily write the files back to disk using the [[_WRITEFILE]] command, i.e. you could create your own simple installer or package manager.
* Embedded images, sounds or fonts can be passed directly to [[_LOADIMAGE]], [[_SNDOPEN]] or [[_LOADFONT]] respectively when using the ''memory load'' capabilities of these functions.
* Embedded images, sounds or fonts can be passed directly to [[_LOADIMAGE]], [[_SNDOPEN]] or [[_LOADFONT]] respectively when using the ''memory load'' capabilities of these functions.


Line 55: Line 59:
{{Cl|END}}
{{Cl|END}}
{{CodeEnd}}
{{CodeEnd}}
{{Small|Code by RhoSigma}}
{{Small|Example by RhoSigma}}




{{PageSeeAlso}}
{{PageSeeAlso}}
* [https://qb64phoenix.com/forum/showthread.php?tid=2740 Featured in our "Keyword of the Day" series]
* [[$EMBED]]
* [[$EMBED]]
* [[DATA]], [[RESTORE]], [[READ]]
* [[DATA]], [[RESTORE]], [[READ]]

Latest revision as of 22:19, 28 June 2024

The _EMBEDDED$ function is used to recall the data of a file which was earlier embedded into the EXE file using the $EMBED metacommand. You can roughly compare this to a RESTORE to any DATA block and then using READ to retrieve the data.


Syntax

filedata$ = _EMBEDDED$("handle")


Parameters

IMPORTANT
  • The parameter handle must be given as a single literal string enclosed in quotes, variables cannot be used here.
  • Your inputs are checked while typing to ensure its validity, warnings (if any) will be displayed immediately in the IDE status area.
  • The filedata$ will receive the embedded file data as a single contiguous string, just as you would regularly OPEN the file and read its entire contents into that string.
  • The handle is a unique case sensitive identifier beginning with a letter and only containing lower/upper case letters and/or numbers. It must exactly match the handle value used to $EMBED the respective file.
    • You can compare this identifier to the line label in front of a DATA block, which is later used in a RESTORE call to set the READ pointer to exactly that DATA block.


Description

  • All embedded files can be recalled individually by using its respective handle identifier.
    • If required, decompression is done internally, hence you always get back the original file contents.
  • Recalling a file multiple times is possible, but in regard for the needed decompression time considered inefficient. Rather recall the file once and store the result in a STRING variable, if you know you need it multiple times in your program.
  • To easily embed a file into your compiled EXE file use the $EMBED metacommand.
  • Embedding files can be useful to deliver a program inclusive all required assets in just one EXE file.
  • No more worries whether a user installs your program correctly and retains the required folder structure.
  • If required, you can easily write the files back to disk using the _WRITEFILE command, i.e. you could create your own simple installer or package manager.
  • Embedded images, sounds or fonts can be passed directly to _LOADIMAGE, _SNDOPEN or _LOADFONT respectively when using the memory load capabilities of these functions.


Availability

  • none

    none

  • v3.10.0

    v3.10.0

  • Apix.png
  • yes

    yes

  • yes

    yes

  • yes

    yes


Examples

Example
Embeds two image files into the compiled EXE, then memory loads and displays it.
$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&

END
Example by RhoSigma


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=EMBEDDED$&oldid=9019"