{{DISPLAYTITLE:_LOADIMAGE}}
The '''_LOADIMAGE''' function loads an image into memory and returns valid [[LONG]] image handle values that are less than -1. 


{{PageSyntax}}
:: handle& = '''_LOADIMAGE& ('''''filename$''[, ''mode&'']''')'''


{{Parameters}}
* ''filename'' is literal or variable [[STRING]] file name value.
* Optional ''mode'' [[INTEGER]] values can be any valid screen mode except zero, 256 color, 32 bit or 33 hardware image.


{{PageDescription}}
* File types supported:  BMP, JPG, PNG, GIF, PNM, XPM, XCF, PCX, TIF, LBM, and TGA. A path can also be given.
* The ''mode&'' can designate 256(8 bit), 32 bit color or 33 in GL. Omit to use the current graphic screen settings.
* '''QB64GL''' mode 33 images are '''hardware''' accelerated and are created using [[_LOADIMAGE]] or [[_COPYIMAGE]] ([[_NEWIMAGE]] will later)
* Loaded images can be read invisibly using [[POINT]]. Image coordinates start at 0 up to the [[_WIDTH (function)|_WIDTH]] - 1 and [[_HEIGHT]] - 1.
* Images can be made into a program [[SCREEN (statement)|SCREEN]] or page adopting the size and palette settings or placed using [[_PUTIMAGE]].
* Returns -1 as an invalid handle if it could not load the image. Valid {{KW|LONG}} handle returns are less than -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]].'''


{{PageErrors}}
* 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 [[SCREEN]] 0 ''mode&'' 32 must be designated!''' When loading an [[_ICON]] image use 32 for the mode also.
* '''QB64 SDL does not support icon files! A bad handle value will occur using _LOADIMAGE! See [[_ICON]] example 2.''' 


''Example 1:''  Already in SCREEN 13 and want computer to match the 32-bit jpg/etc. 
colors to the current palette:
{{CodeStart}} '' ''
{{Cl|SCREEN (statement)|SCREEN}} 13
i& = {{Cl|_LOADIMAGE}}("mypic.jpg") 
{{Cl|_PUTIMAGE}}, i& '' ''
{{CodeEnd}}


''Example 2:'' Already in SCREEN 13 but want to load an 8-bit image and adopt its 
palette as the current palette:
{{CodeStart}} '' ''
{{Cl|SCREEN (statement)|SCREEN}} 13
i& = {{Cl|_LOADIMAGE}}("mypic256col.bmp", 256)
{{Cl|_COPYPALETTE}} i&, 0
{{Cl|_PUTIMAGE}}, i& '' ''
{{CodeEnd}}


''Example 3:'' Want to display an image in 32-bit color using its resolution as a program screen:
{{CodeStart}} '' ''
i& = {{Cl|_LOADIMAGE}}("mypic.jpg", 32)
{{Cl|SCREEN (statement)|SCREEN}} i& '' ''
{{CodeEnd}}


''Example 4:'' [[DRAW]]ing and rotating an image 360 degrees using Turn Angle. [[POINT]] is used to read the invisible image source.
{{CodeStart}}
{{Cl|SCREEN (statement)|SCREEN}} {{Cl|_NEWIMAGE}}(800, 600, 32)
img& = {{Cl|_LOADIMAGE}}("QB64.PNG")                           'load the image file to be drawn

wide% = {{Cl|_WIDTH (function)|_WIDTH}}(img&): deep% = {{Cl|_HEIGHT}}(img&)
TLC$ = "BL" + {{Cl|STR$}}(wide% \ 2) + "BU" + {{Cl|STR$}}(deep% \ 2)  'start draw at top left corner
RET$ = "BD BL" + {{Cl|STR$}}(wide%)                            'return to left side of image
{{Cl|_SOURCE}} img&
{{Cl|_DEST}} 0
DO
  {{Cl|FOR...NEXT|FOR}} angle% = 0 {{Cl|TO}} 360 {{Cl|STEP}} 15
    {{Cl|CLS}}
    {{Cl|DRAW}} "BM400, 300" + "TA=" + {{Cl|VARPTR$}}(angle%) + TLC$
    {{Cl|FOR...NEXT|FOR}} y = 0 {{Cl|TO}} deep% - 1
      {{Cl|FOR...NEXT|FOR}} x = 0 {{Cl|TO}} wide% - 1
        {{Cl|DRAW}} "C" + {{Cl|STR$}}({{Cl|POINT}}(x, y)) + "R1"            'color and DRAW each pixel
      {{Cl|NEXT}}
      {{Cl|DRAW}} RET$
    {{Cl|NEXT}}
    {{Cl|_DISPLAY}}                         'NOTE: CPU usage will be HIGH!
  {{Cl|NEXT}}
{{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|INKEY$}} > "" '' ''
{{CodeEnd}}
{{small|Code by Ted Weissgerber}}
:''NOTE:'' The ''QB64.PNG'' file picturing the QB64 bee can saved from the top of the [http://www.qb64.net/forum/index.php QB64 forum]. Speed varies with image size.


''See Examples:''
* [[SAVEIMAGE]] (QB64 Image to Bitmap SUB by Galleon)

* [[Program ScreenShots]] (Member program for legacy screen modes)

* [[ThirtyTwoBit SUB]] (QB64 Image area to bitmap)


{{PageSeeAlso}}
* [[_FREEIMAGE]], [[_ICON]] {{text|(Icons can be used in GL only!)}}
* [[_PUTIMAGE]], [[_MAPTRIANGLE]]
* [[_NEWIMAGE]], [[_COPYIMAGE]] 
* [[_PRINTIMAGE]] (printer)
* [[_PALETTECOLOR (function)]], [[_COPYPALETTE]], [[_ICON]]
* [[SCREEN (statement)]]
* [[Hardware images]]
* [[Bitmaps]], [[Icons and Cursors]], [[GIF Images]]


{{PageNavigation}}