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 as 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.
  • SXBR2: Applies the Super-xBR 2x pixel scaler on the image.
  • MMPX2: Applies the MMPX Style-Preserving 2x pixel scaler on the image.
  • HQ2XA: Applies the High Quality Cartoon 2x pixel scaler on the image.
  • HQ2XB: Applies the High Quality Complex 2x pixel scaler on the image.
  • HQ3XA: Applies the High Quality Cartoon 3x pixel scaler on the image.
  • HQ3XB: Applies the High Quality Complex 3x pixel scaler on the image.

Description

• Image file formats JPG, PNG, TGA, BMP, PSD, GIF, HDR, PIC, PNM, PCX, SVG, ICO, CUR and QOI 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 VGA 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.
• Use the various pixel scalers to scale and load extremely low resolution (retro) graphics without blurring.

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.
• SVG and QOI support was added in QB64-PE v3.9.0.
• Pixel scaler support was added in QB64-PE v3.9.0.
• ICO and CUR support was added in QB64-PE v3.14.0.

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

Load and scale 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, hq3xa") ' load image file from memory and scale it using a pixel scaler 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

---

Example 4

Load SVG vector graphics data from memory and display it on the screen.

OPTION _EXPLICIT $RESIZE:SMOOTH RESTORE svg_data DIM AS STRING svg, buffer DO READ buffer svg = svg + buffer LOOP WHILE LEN(buffer) > 0 DIM img AS LONG: img = _LOADIMAGE(svg, 32, "memory") SCREEN _NEWIMAGE(_WIDTH(img) \ 2, _HEIGHT(img) \ 2, 32) _PUTIMAGE , img END svg_data: DATA "<svg xmlns='http://www.w3.org/2000/svg' width='1000pt' height='1000pt' viewBox='0 0 1000 1000'><g fill='#201701'" DATA "><path d='M107 94c-3-1 2-4 2-1l-2 1ZM96 672h35l24 168 220-43 4 21-255 42-28-188ZM521 768l41-8 5 25c0 2-3 3-4 3l-" DATA "36 6-6-26Z' opacity='.1'/></g><g fill='#020092'><path d='m107 94 2-1 683 134 76 328 2 7 23 101-176 35-3-5-24-104" DATA " 108-11 14 65 59-9-40-168h-60l17 78-84 7-18-82c0-1 0-3-2-2h-21l-17-71 169 7-12-54-26-1c-5-16-8-32-11-49 9 1 17 3" DATA " 26 3l-12-53-220-38 29 146c-25-3-50-9-74-14l-28-144-329-57 20 134c-15-1-30-5-46-8v-1L107 94Z'/><path d='m284 200" DATA " 140 22 6 33-25-2c4 23 9 46 12 70l-116-23h-1l-16-100ZM640 255l90 13 7 34-85-11c-2 0-5 0-5-3l-7-33ZM137 300l46 8 " DATA "10 69 31 1c3 28 9 56 13 85l80 5 8 2-120 1 3 22-43-2-28-191ZM305 330l77 13c2 0 4 2 4 4-26 0-53-3-79-4l-2-13ZM656 " DATA "330l89 8 9 39-89-5-9-42ZM519 368c8-1 16 2 24 3l50 8 4 15c11 1 23 0 35 2l7 33-22-2 9 40h-16l9 44c-20-1-41-1-61-3-" DATA "6 0-12 0-18-2l31-1-3-17 38 3c-1-11-4-21-7-31-24-2-48-6-72-7l3 15-60 1c-5-27-12-54-15-81l59 3 6 28 72 9-5-27-63-9" DATA "-5-24ZM325 425l77 1 8 43-77 1c-3-15-7-30-8-45Z'/></g><path fill='#00bbfd' d='m158 142 329 57 28 144 4 25 5 24-10" DATA "-1-59-3-27-1 7 39h-33l-77-1-7-43-94-4-31-1-10-69-5-32-20-134m126 58 16 100h1c0 10 3 20 4 30l2 13c26 1 53 4 79 4l" DATA "36 3-5-27c-3-24-8-47-12-70l25 2-6-33-140-22Z'/><path fill='#037efe' d='m560 211 220 38 12 53c-9 0-17-2-26-3 3 17" DATA " 6 33 11 49l26 1 12 54-169-7h-14c-12-2-24-1-35-2l-4-15-4-22-29-146m80 44 7 33c0 3 3 3 5 3l85 11-7-34-90-13m16 75" DATA " 9 42 89 5-9-39-89-8Z'/><g fill='#070636'><path d='m71 256 61 11v1c2 11 4 21 4 32l-23-4 29 195c8 1 16-2 23 3l11 " DATA "75h-24c7 38 12 76 17 114l16 106 22-4 2 13 446-88c5 2 10 0 14 0l35-6v-4l12-2c2 10 6 20 7 31a19145 19145 0 0 0-202" DATA " 39l-146 29-220 43-24-168-37-255-23-161ZM868 555c2 2 2 5 2 7l-2-7Z' opacity='.4'/></g><g fill='#030173'><path d=" DATA "'M132 268c16 3 31 7 46 8l5 32-46-8h-1c0-11-2-21-4-32ZM301 300l116 23 5 27-36-3c0-2-2-4-4-4l-77-13c-1-10-4-20-4-3" DATA "0ZM515 343c24 5 49 11 74 14l4 22-50-8c-8-1-16-4-24-3l-4-25ZM224 378l94 4 7 43c1 15 5 30 8 45h-8l-8-2-80-5c-4-29-" DATA "10-57-13-85ZM428 387l27 1c3 27 10 54 15 81h-60l-8-43h33l-7-39ZM514 391l10 1 63 9 5 27-72-9-6-28ZM632 396h14l17 7" DATA "1h-37l-9-40 22 2-7-33ZM527 453c24 1 48 5 72 7 3 10 6 20 7 31l-38-3-4-20h-34l-3-15ZM165 491l43 2 37 243 359-59-22" DATA "-115c-79 5-157 12-236 18l-11-67 205-7c6 2 12 2 18 2 20 2 41 2 61 3l17 84 54-6 24 104 3 5h-1l-12 2-49 10-446 88-2" DATA "-13-31-216-11-75v-3Z'/><path d='m491 609 6-1 8 44-143 19-8-47 137-15Z'/></g><path fill='#013f59' d='m113 296 23 " DATA "4h1l28 191v3c-7-5-15-2-23-3l-29-195Z' opacity='.4'/><path fill='#000314' d='M26 404c23 3 46 9 68 13l37 255H96l28" DATA " 188 255-42-4-21 146-29 6 26 36-6c1 0 4-1 4-3l-5-25 11-2 11 50-23 5-441 86c-7 2-14 4-22 4L26 404Z' opacity='.1'/" DATA "><path fill='#f87d03' d='M771 466h60l40 168-59 9-14-65-108 11-54 6-17-84-9-44h74c2-1 2 1 2 2l18 82 84-7-17-78Z'/" DATA "><path fill='#febd04' d='m470 469 60-1h34l4 20 3 17-31 1-205 7 11 67c79-6 157-13 236-18l22 115-359 59-37-243-3-2" DATA "2 120-1h8l77-1h60m21 140-137 15 8 47 143-19-8-44-6 1Z'/><g fill='#5d470f'><path d='M152 569h24l31 216-22 4-16-10" DATA "6c-5-38-10-76-17-114ZM655 710l49-10v4l-35 6c-4 0-9 2-14 0Z' opacity='.4'/></g></svg>" DATA ""

See also

• _FREEIMAGE
• _PUTIMAGE, _MAPTRIANGLE
• _NEWIMAGE, _COPYIMAGE
• _PRINTIMAGE (printer)
• _PALETTECOLOR (function), _COPYPALETTE, _ICON
• SCREEN
• _SAVEIMAGE
• 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