LOADIMAGE

The _LOADIMAGE function loads an image into memory and returns valid LONG image handle values that are less than -1.

Syntax

handle& = _LOADIMAGE(fileName$[, [mode&][, requirements$]])

Parameters

• filename$ is literal or variable STRING file name value.
• Optional mode& LONG values can be:
  • 32 = 32-bit image.
  • 33 = 32-bit hardware image.
  • 256 = 8-bit (256 color) image using the QB64-PE master palette.
  • 257 = 8-bit (256 color) image using an adaptive palette.
• Optional requirements$ STRING values can be a combination of (version 3.6.0 and up):
  • HARDWARE: Loads the image as a 32-bit hardware image. This can be used instead of mode 33 (above).
  • ADAPTIVE: Loads the image an 8-bit (256 color) image using an adaptive palette. This can be used instead of mode 257 (above).
  • MEMORY: This will treat filename$ as a memory buffer containing the image file instead of a file name.

Description

• Various common image file formats like JPG, PNG, TGA, BMP, PSD, GIF, HDR, PIC, PNM and PCX are supported. A path can also be given.
• The mode& parameter can be 32, 33,256 or 257. Omit to use the current graphic screen settings.
• Mode 33 images are hardware accelerated and are created using _LOADIMAGE or _COPYIMAGE (version 1.000 and up).
• Mode 256 images are loaded using the QB64-PE master palette. This is the same palette that is used for 256 color screens like SCREEN 13.
• Mode 257 images are loaded using an adaptive palette making these images look better than mode 256 when used with 32-bit color screens (version 3.1.0 and up).
• Loaded images can be read invisibly using POINT. Image coordinates start at 0 up to the _WIDTH - 1 and _HEIGHT - 1.
• Images can be made into a program SCREEN or page adopting the size and palette settings or placed using _PUTIMAGE.
• Returns -1 as an invalid handle if it can't load the image. Valid LONG handle returns are less than -1 (handle& < -1).
• Valid images only need to be loaded once. The handle can be used repeatedly until freed.
• Images are not deallocated when the SUB or FUNCTION they are created in ends. Free them with _FREEIMAGE.

Errors

• Some picture file images may not load when a mode& value is designated. Try loading it without a mode& designation.
• It is important to free unused or discarded images with _FREEIMAGE to prevent CPU memory overflow errors.
• In text-only SCREEN 0, mode& 32 must be specified. When loading an _ICON image use 32 for the mode& too.

Availability

• 

  v0.800

• 

  all

• 
• 

  yes

• 

  yes

• 

  yes

• Mode 33 was added in QB64 v1.0, which makes it also available in all QB64-PE versions.
• Mode 257 was added in QB64-PE v3.1.0, hence it's not available in the original QB64 versions.
• In QB64-PE v3.6.0 this function got a new optional parameter requirements$ and the ability to load image files from memory.

Examples

Example 1

To display an image in 32-bit color using its resolution as a program screen.

i& = _LOADIMAGE("mypic.jpg", 32) SCREEN i&

---

Example 2

DRAWing and rotating an image 360 degrees using Turn Angle. POINT is used to read the invisible image source.

SCREEN _NEWIMAGE(800, 600, 32) img& = _LOADIMAGE("QB64.PNG") 'use any 24/32 bit image wide% = _WIDTH(img&): deep% = _HEIGHT(img&) TLC$ = "BL" + STR$(wide% \ 2) + "BU" + STR$(deep% \ 2) 'start draw at top left corner RET$ = "BD BL" + STR$(wide%) 'return to left side of image _SOURCE img& _DEST 0 DO FOR angle% = 0 TO 360 STEP 15 CLS DRAW "BM400, 300" + "TA=" + VARPTR$(angle%) + TLC$ FOR y = 0 TO deep% - 1 FOR x = 0 TO wide% - 1 DRAW "C" + STR$(POINT(x, y)) + "R1" 'color and DRAW each pixel NEXT DRAW RET$ NEXT _DISPLAY 'NOTE: CPU usage will be HIGH! NEXT LOOP UNTIL INKEY$ > ""

Code by Ted Weissgerber

---

Example 3

To load an image from memory and display it on the screen

OPTION _EXPLICIT DIM Bee& ' the image file DIM cx%, cy% ' center x,y coordinate for image RESTORE Data_tbee0_png_2314 Bee& = _LOADIMAGE(LoadResource, 32, "memory") ' load image file into memory SCREEN _NEWIMAGE(640, 480, 32) ' enter a graphics screen CLS , _RGB32(127, 127, 127) ' clear the screen with gray LOCATE 2, 15 ' position text cursor PRINT "An image loaded into memory and placed on the screen." cx% = (640 - _WIDTH(Bee&)) \ 2 ' calculate x center position cy% = (480 - _HEIGHT(Bee&)) \ 2 ' calculate y center position _PUTIMAGE (cx%, cy%), Bee& ' place image onto center of screen SLEEP ' wait for key stroke _FREEIMAGE Bee& ' remove image from memory SYSTEM ' return to OS Data_tbee0_png_2314: DATA 2314,2988,-1 DATA eJx1VmdUU9kWDiihKDGEariKEKzUoV4FHWMgCYj0iVIVKeIocgNKiSCIkQuEZGBQRARxgCdNLNRQFYgE DATA pGMARYOSCCqiSAkgUia8f28t3zrfPvtb31lnn732+bF3oqM9SV4OK4dAIORtyFbOYg+vmwxSvFt+tF0/ DATA QJ4+SrJCrK2vew0FaWJFFiK7hSIQKM66SdzUQakjEDLFNlZ414jhr3wPO6XjAPJ7V4D6yajg4eHaeQx/ DATA 7iqd7Pt2sNckOvBk8pNWtXNM5hOOmguzyMk3YSFCVqEeaS25T0YyLjYpFk23flFcKIp3biLzZgI1jjUe DATA yriNaumc9Oye7DTKab9l/cprfEaYtZZ121hdEn1arRTCGXKa0NIEYDP1f0nLr0Qx+aVINfylyEl101GU DATA w9uirxhQ0dLryI+G/ZemdqAEO1Al7V1d1hcu6C/zPjBovyt8IQIc/DpY4Qlp2/JEw12huF5G4dIR3owi DATA CUu1ynOSlUDYLR7AMuNAyRAlDJOowCSObfNDwjM1trp4sFhhnrhQq0Ot/qKLPPCCWpe3uXr4aOp5PXxZ DATA 5UZfnM1b9kUlb0FK2MMQWOdqYZ7Isu6wlYBN/bynlfj3TFXDgHfSm23+7JeR2PC6boF3+E5L7jR7TXL7 DATA /IAAPxW5PBCNKoIqstpJwbM+2lhGLx9CD33Z1PtHOCLb9Of7+XjKpCvisINvav3sf3KKfPbEjLw8of10 DATA EIW26HjrVr7F65I01NCI4MtLpwbqHhGHEEdySBRecVDePneX29LobvntaWzFezUsm15QnWmYUS+TCh7o DATA nsJfHtBnX+KdohNKRI5rnShUnchaLF3MerchFUSmqU7PURTjkfp4kDV6+fhvJtDWMCrC8HpeaYi0u05V DATA kx5wkGkdwuPHY+BaC6en3fJAqfKbXkrNhgAI8ZgpnLI4bhg1tQ8QRqy+xxK/VTftRZXrwfS8MbtDD28E DATA WxczDVaOVireEMV5f/WhE3R21aIjXycPCm1/UMTJw8qAvTtKltu2YmYZA8lXQfURPNlHVE/9N3Hj/ccg DATA dZiCnzBjiSnbs0rKWxgxXaiYDiWjwpocwExbM4GgXR4yCrsHtwSi7bbAab8xGbvN7xX54Zbpvhcfb7oP DATA 1Uf1b+gDHwwCNBCbNJS3ujgFGbXlSx3ZFKuitPuap4gbQyJM0xKeaeaOOwojfuRLx4Pe8qJmeSBXnBSJ DATA /6Sy8GAZUgsi96xVhzwEGg5wUKxh3DnH8PN6VgIob2z9xqN42j+JQlH5IT8M64tIqnB/BXbgemQmuZOn DATA 5o67R4PZASPHE3NrDbeYwhQhLRpPHI1YebBFCCXLL+AUqTe+eSZPNFu6bvO8HiqlwySacJUf2kOFXAse DATA 2K38wGqg6Y9C/U7C5+7nWxN9z7PX+ONYdZvmICD3HKvW95zEKUlW0gYdKGwt5CU4Yn87qdrlvpaSXPvJ DATA krVgFe7rlQ4n6qnnGwEEXQiVjDsK1NRttPTA/oEQMmg/5RU/c/CoU9VlWdtw/dairwzHsiBN+w8Gh6cH DATA f8ywzK4RaBfEDEx9itj5RkXAm7few69R86+7dS+qxzlrpM5OlXS/Crja8s+AfEZi2U0ZJZZd6f7kWmUc DATA MKFP7H6zsNrDwW2p0XmS1MK8sDPIlHSARcniAbc6qmSC9lfEt7mMOqo8Fpf4LH/5RGggKzSZqR09FIIm DATA LbmznqRqO6NynmInsl35SRf9bxmlkjmuDQqJgd4ef9Z5nN3jPWUBTDQZuJzxJ0nXfTBv/xCnhMBEGnOt DATA y0W9beM1qbKPKuMI/JBFCXiO9Cjc/nm/CLCnkk1JuU/azPXgvqLIBpcf3tVAYquWpimp2EVUZaB4Q+64 DATA hR5MBigeLPGb21EF/KS2dEKzT+WYo2rm2Zpni+LPrb8y+FEWVQeX0aSKtqN0pM5e8hlhswdCMpo0v6qf DATA 9IzW10vW8EDhAJrq7KfswtmZwJ3KKIUdnjnVWnr5d0xhL2ACb2gMZm2Oq7lKcAtNQKYO2hxz7tAszRri DATA J71MwGpWMnB9J7SrgbTTrXfUwcm7EQxiXoKVVvphcs/CEucOhpufifqsCoxCr1xv5X5zbx59HAzZvagp DATA 874bkRZWhYFv0lt8fhyst5w2K9rtfLkv5NX+YzkTSo2qeqQdAa8ZHM2Vjvb2pqz9oSlpadcmJ8/7+ftr DATA qjCY6pPYgybqeXCAMBJvdlfVr+PRyplFB+2ZgNyYoM2J9bc/LYk2Vawtb3VX6To8u/y5cG3UlxdlHtT8 DATA /oSuCoFCUSkrLx97p/EXd2xBORHnWH0KbWqquf0v35H6yASuMB4c8fT6pEYaM9fIXS5ZcBGkpJN4PPqz DATA kZwWXZSO8esKOds+sFOlwr0jSEU6eESSngxlSPiYdHQFAZSAV0U5vvRr4fNOVTsqf9p1lZkzCH4Smfvs DATA 010OdjSWh2kslzkYCeYJlKli3NInTmcfQ/0LHogzL8a23inZxL20l8a3fZfpxq7Rj280LU9Z/Oo11D/d DATA 8THQa2bvw2WTDcdmC/JGuQ6OP1dMXGN+KuxrXH1mhBb8t5es47u5nI66V20ALhvkhZ4p1TWm5m+Fb59l DATA En83Ni5MnxBxRl2AiRL2jRj+C1Lp1NHwzSY018ZH2R4EBbjFw8GjhntrcLYBu7GcxvUtHYTBje8Na+/c DATA GwJvDGVjYOmM5LDYgbi58Vo15Opiv7NTMQwOlE371lseqhdhSLu2V2GkqXYXAErPiyUJ0n0tTZQgIwrs DATA vFIW9wa0MjCmgov0XSVDl05s+2xivHT24xKmYVpN8B0ND7YV0uiuP/YwY/dpVBJtS4H7GBgWXU/rcaMO DATA 0/JDoxNaFs+f25NGTThR8EyYcqjUjdMamtQsk5jgPzu72+WnCrEXWlQgt7JS7JGALjna/dWf0VHxfQtG DATA 0YcZIKBUQIE2+t+RQsI3O2SzPVdJgEQxPk4OlwLOxeYveaOrXXb8smk3/Z+JgAC8lUkOW93AGx2tePu3 DATA 9ax4lEHYWNtbPTxyKu5fF0s/3Q== ' Convert a base64 string to a normal string FUNCTION DecodeBase64$ (s AS STRING) CONST BASE64_CHARACTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/" DIM AS STRING buffer, result DIM AS _UNSIGNED LONG i DIM AS _UNSIGNED _BYTE char1, char2, char3, char4 FOR i = 1 TO LEN(s) STEP 4 char1 = INSTR(BASE64_CHARACTERS, CHR$(ASC(s, i))) - 1 char2 = INSTR(BASE64_CHARACTERS, CHR$(ASC(s, i + 1))) - 1 char3 = INSTR(BASE64_CHARACTERS, CHR$(ASC(s, i + 2))) - 1 char4 = INSTR(BASE64_CHARACTERS, CHR$(ASC(s, i + 3))) - 1 buffer = CHR$(_SHL(char1, 2) OR _SHR(char2, 4)) + CHR$(_SHL(char2 AND 15, 4) OR _SHR(char3, 2)) + CHR$(_SHL(char3 AND 3, 6) OR char4) result = result + buffer NEXT ' Remove padding IF RIGHT$(s, 2) = "==" THEN result = LEFT$(result, LEN(result) - 2) ELSEIF RIGHT$(s, 1) = "=" THEN result = LEFT$(result, LEN(result) - 1) END IF DecodeBase64 = result END FUNCTION ' Loads a binary file encoded with Bin2Data ' Usage: ' 1. Encode the binary file with Bin2Data ' 2. Include the file or it's contents ' 3. Load the file like so: ' Restore label_generated_by_bin2data ' Dim buffer As String ' buffer = LoadResource ' buffer will now hold the contents of the file FUNCTION LoadResource$ DIM AS _UNSIGNED LONG ogSize, resize DIM AS _BYTE isCompressed READ ogSize, resize, isCompressed ' read the header DIM AS STRING buffer, result ' Read the whole resource data DO WHILE LEN(result) < resize READ buffer result = result + buffer LOOP ' Decode the data buffer = DecodeBase64(result) ' Expand the data if needed IF isCompressed THEN result = _INFLATE$(buffer, ogSize) ELSE result = buffer END IF LoadResource = result END FUNCTION

Adapted from example code by Terry Ritchie

More examples

• SAVEIMAGE
• Program ScreenShots
• ThirtyTwoBit SUB

See also

• _FREEIMAGE, _ICON
• _PUTIMAGE, _MAPTRIANGLE
• _NEWIMAGE, _COPYIMAGE
• _PRINTIMAGE (printer)
• _PALETTECOLOR (function), _COPYPALETTE, _ICON
• SCREEN
• Hardware images
• Bitmaps, Icons and Cursors, GIF Images

---

Navigation: Main Page with Articles and Tutorials Keyword Reference - Alphabetical Keyword Reference - By usage Report a broken link