_LOADIMAGE

From QB64 Phoenix Edition Wiki
Revision as of 04:37, 23 September 2023 by A740g (talk | contribs) (Fix typo)
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 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.


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


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=8526"