source: project/wiki/eggref/5/stb-image @ 35685

Last change on this file since 35685 was 35685, checked in by Mario Domenech Goulart, 16 months ago

eggref/5/stb-image: fix egg name and add "Repository" section

File size: 2.6 KB
Line 
1== stb-image
2[[toc:]]
3This is a [[http://call-cc.org|CHICKEN]] egg that wraps [[https://github.com/nothings/stb|stb_image.h]] version 2.19 from
4Sean Barrett and friends. It works on [[http://call-cc.org|CHICKEN]] 4 and 5.
5
6== Repository
7
8[[https://github.com/kristianlm/chicken-stb-image|https://github.com/kristianlm/chicken-stb-image]]
9
10== API
11[[toc:]]
12<procedure> (read-image #!key channels)</procedure>
13<procedure> (load-image u8vector #!key channels)</procedure>
14
15Decodes an image into raw pixel data. {{read-image}} reads the image
16from from {{(current-input-port)}} while {{load-image}} gets this from the
17provided u8vector. The image type is detected by content, and may be:
18JPEG, PNG, TGA, BMP, PSD, GIF, HDR, PIC, PNM as explained in the
19heading comments of {{stb_image.h}}.
20
21Both procedures return 4 values:
22
23# raw pixel data (as u8vector)
24# width
25# height
26# number of channels
27
28You can force the number of channels with the {{channels}} keyword. If
29{{channels}} is {{#f}} or not given, the number of channels in the
30original image will be used.
31
32The size of the pixel data blob is always {{(* width height channels)}}
33bytes. The first pixel is the top-left-most in the image. Each pixel
34is {{channel}} number of bytes long. The number of channels define the
35pixel color, interleaved as follows:
36
37# grey
38# grey, alpha
39# red, green, blue
40# red, green, blue, alpha
41
42{{read-image}} may read beyond the image data, so the data in
43{{current-input-port}} should contain only one image.
44
45<procedure> (read-image-info)</procedure>
46<procedure> (load-image-info blob)</procedure>
47
48Like {{read-image}} and {{load-image}}, but does not load pixel data and
49should be faster. Returns three values:
50
51# width
52# height
53# number of channels
54
55Note that on 32-bit systems, blobs cannot be larger than 16M. This
56limits image sizes as pixel data is stored as blobs.
57
58
59=== Examples
60For quick testing, you can read PNGs from ImageMagick's {{convert}}:
61
62    $ convert -size 4x4 xc:blue -draw 'line 0,0 4,4' png:- | csi -R stb-image -p '(read-image)'
63    #u8(0 0 0     0 0 234   0 0 255   0 0 255
64        0 0 234   0 0 0     0 0 234   0 0 255
65        0 0 255   0 0 234   0 0 0     0 0 234
66        0 0 255   0 0 255   0 0 234   0 0 0)
67    4
68    4
69    3
70
71Which reveal the black line along the diagonal and informs that the
72image is 4x4 with 3-channels.
73
74
75=== Known limitations
76
77===== backwards seek not implemented
78Some special-case images try to seek backwards in the internal
79API. This hasn't been implemented due to increased complexity: you may
80see a "backwards seek not implemented" error. If this is a
81show-stopper, contact the author.
82
Note: See TracBrowser for help on using the repository browser.