_LOADIMAGE

From QB64 Phoenix Edition Wiki
Revision as of 16:03, 21 July 2024 by A740g (talk | contribs) (Add info on .cur and .ico support and remove outdated links)
Jump to navigation Jump to search

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

    v0.800

  • all

    all

  • Apix.png
  • yes

    yes

  • yes

    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


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=LOADIMAGE&oldid=9043"