Add load_aseprite_file function and example usage in ASEPRITE.BAS

Author: grymmjack

ASEPRITE/ASEPRITE-INFO.BAS

@@ -886,7 +886,7 @@ FUNCTION format_number$ (value AS LONG, width AS INTEGER)
     format_number$ = result
 END FUNCTION
 
-$IF GJ_LIB_UNIFIED_TESTING = DEFINED AND GJ_LIB_INC_BI = UNDEFINED THEN
+$IF GJ_LIB_UNIFIED_TESTING = DEFINED AND GJ_LIB_INC_BM = UNDEFINED THEN
     '$INCLUDE:'../_GJ_LIB.BM'
 $END IF
 

ASEPRITE/ASEPRITE.BAS

@@ -0,0 +1,49 @@
+''
+' QB64_GJ_LIB
+' GRYMMJACK'S ASEPRITE LIB
+'
+' Simple example of using ASEPRITE in QB64
+'
+' USAGE:
+'   Insert '$INCLUDE:'path_to_GJ_LIB/ASEPRITE/ASEPRITE.BI' at the top of file
+'   Insert '$INCLUDE:'path_to_GJ_LIB/ASEPRITE/ASEPRITE.BM' at the bottom of file
+' 
+' @see https://github.com/aseprite/aseprite/blob/main/docs/ase-file-specs.md
+' @author Rick Christy <grymmjack@gmail.com>
+'
+$IF GJ_LIB_UNIFIED_TESTING = DEFINED AND GJ_LIB_INC_BI = UNDEFINED THEN
+    '$INCLUDE:'../_GJ_LIB.BI'
+$END IF
+
+'$INCLUDE:'ASEPRITE.BI'
+
+$CONSOLE
+
+DIM filename  AS STRING
+DIM aseprite_image AS LONG
+
+filename = "test-files/DJ Trapezoid - Pumpkin Head.aseprite"
+
+_ECHO "Loading: " + filename$
+
+aseprite_image& = load_aseprite_file(filename$)
+IF aseprite_image& = 0 THEN
+  _ECHO "Failed to load ASEPRITE image: " + filename$
+  SYSTEM 0
+END IF
+
+_TITLE "ASEPRITE ImageViewer"
+SCREEN _NEWIMAGE(_WIDTH(aseprite_image&), _HEIGHT(aseprite_image&), 32)
+_SCREENMOVE _MIDDLE
+_SOURCE aseprite_image&
+_DEST 0
+_PUTIMAGE
+SLEEP
+
+SYSTEM 1
+
+$IF GJ_LIB_UNIFIED_TESTING = DEFINED AND GJ_LIB_INC_BM = UNDEFINED THEN
+    '$INCLUDE:'../_GJ_LIB.BM'
+$END IF
+
+'$INCLUDE:'ASEPRITE.BM'

ASEPRITE/ASEPRITE.BM

@@ -2109,6 +2109,34 @@ FUNCTION create_full_composite_image& (filename AS STRING, frame_index AS INTEGE
 END FUNCTION
 
 
+''
+' Loads an ASEPRITE file and returns an ASEPRITE_IMAGE structure
+'
+' @param filename Path to ASEPRITE file
+' @return LONG Image handle for composite image, or 0 on failure
+'
+FUNCTION load_aseprite_file& (filename AS STRING)
+  DIM ase_img   AS ASEPRITE_IMAGE
+  DIM composite AS LONG
+
+  IF ASEPRITE_DEBUG_MODE THEN
+      _ECHO "Loading: " + filename$
+  END IF
+  CALL load_aseprite_image(filename$, ase_img)
+
+  IF ase_img.is_valid = _FALSE THEN
+      IF ASEPRITE_DEBUG_MODE THEN
+          _ECHO "Failed to load ASEPRITE: " + ase_img.error_message
+      END IF
+      load_aseprite_file& = 0
+      EXIT FUNCTION
+  ELSE
+    composite& = create_composite_image_from_aseprite&(ase_img)
+    load_aseprite_file& = composite&
+  END IF
+
+END FUNCTION
+
 ''
 ' Creates a simple composite image from an already-loaded ASEPRITE_IMAGE
 ' This implementation composites each layer in file order using