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.
  • ADAPTIVE: Loads the image an 8-bit (256 color) image using an adaptive palette.
  • 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

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