EMBEDDED$: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 10: Line 10:
; IMPORTANT
; IMPORTANT
:* The parameter {{Parameter|handle}} must be given as a {{Text|single literal string|red}} 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 would regularly [[OPEN]] 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.
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.
* 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.
* 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.
* 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 58: 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"