((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/stb-image" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.")) (section 2 "chicken-stb-image" (toc) (p "This is a " (link "http://call-cc.org" "CHICKEN") " egg that wraps " (link "https://github.com/nothings/stb" "stb_image.h") " version 2.19 from Sean Barrett and friends. It works on " (link "http://call-cc.org" "CHICKEN") " 4 and 5.")) (section 2 "Repository" (p (link "https://github.com/kristianlm/chicken-stb-image" "https://github.com/kristianlm/chicken-stb-image"))) (section 2 "API" (toc) (def (sig (procedure " (read-image #!key channels)" (id read-image)) (procedure " (load-image u8vector #!key channels)" (id load-image))) (p "Decodes an image into raw pixel data. " (tt "read-image") " reads the image from from " (tt "(current-input-port)") " while " (tt "load-image") " gets this from the provided u8vector. The image type is detected by content, and may be: JPEG, PNG, TGA, BMP, PSD, GIF, HDR, PIC, PNM as explained in the heading comments of " (tt "stb_image.h") ".") (p "Both procedures return 4 values:") (ol (li "raw pixel data (as u8vector)") (li "width") (li "height") (li "number of channels")) (p "You can force the number of channels with the " (tt "channels") " keyword. If " (tt "channels") " is " (tt "#f") " or not given, the number of channels in the original image will be used.") (p "The size of the pixel data blob is always " (tt "(* width height channels)") " bytes. The first pixel is the top-left-most in the image. Each pixel is " (tt "channel") " number of bytes long. The number of channels define the pixel color, interleaved as follows:") (ol (li "grey") (li "grey, alpha") (li "red, green, blue") (li "red, green, blue, alpha")) (p (tt "read-image") " may read beyond the image data, so the data in " (tt "current-input-port") " should contain only one image.")) (def (sig (procedure " (read-image-info)" (id read-image-info)) (procedure " (load-image-info blob)" (id load-image-info))) (p "Like " (tt "read-image") " and " (tt "load-image") ", but does not load pixel data and should be faster. Returns three values:") (ol (li "width") (li "height") (li "number of channels")) (p "Note that on 32-bit systems, blobs cannot be larger than 16M. This limits image sizes as pixel data is stored as blobs.")) (section 3 "Examples" (p "For quick testing, you can read PNGs from ImageMagick's " (tt "convert") ":") (pre "   $ convert -size 4x4 xc:blue -draw 'line 0,0 4,4' png:- | csi -R stb-image -p '(read-image)'\n   #u8(0 0 0     0 0 234   0 0 255   0 0 255\n       0 0 234   0 0 0     0 0 234   0 0 255\n       0 0 255   0 0 234   0 0 0     0 0 234\n       0 0 255   0 0 255   0 0 234   0 0 0)\n   4\n   4\n   3") (p "Which reveal the black line along the diagonal and informs that the image is 4x4 with 3-channels.")) (section 3 "Known limitations" (section 5 "backwards seek not implemented" (p "Some special-case images try to seek backwards in the internal API. This hasn't been implemented due to increased complexity: you may see a \"backwards seek not implemented\" error. If this is a show-stopper, contact the author.")))))