source: project/wiki/eggref/4/epeg @ 13306

Last change on this file since 13306 was 13306, checked in by felix winkelmann, 11 years ago

added xlib page and removed download links

File size: 6.3 KB
Line 
1[[tags: egg]]
2
3== epeg
4
5[[toc:]]
6
7=== Description
8
9Chicken bindings for the epeg thumbnailer library from the
10[[http://www.enlightenment.org|enlightenment]] project.
11
12=== Author
13
14[[Peter Bex]]
15
16=== Requirements
17
18None
19
20=== Documentation
21
22Epeg works by first opening a file, then setting the desired
23properties of the scaled image.  Upon encoding, these properties are
24taken into account.  Decoding is deferred until encoding of the new
25image takes place for optimal speed.
26
27==== Image creation, destruction and friends
28
29<procedure>(image-open filename) => image</procedure>
30
31Returns a new epeg image object which describes the image stored in
32the file {{filename}}.
33
34<procedure>(image? img) => boolean</procedure>
35
36Determine if {{img}} is an epeg image object.
37
38<procedure>(image-close img)</procedure>
39
40Destroy the image and close the associated file.
41
42<procedure>(image-encode img)</procedure>
43
44Store the encoded image on disk. The filename is determined by
45{{image-file-output-set!}}. Other properties of the image can be set by
46the procedures described below.
47
48==== Image properties
49
50<procedure>(image-size img) => integer integer</procedure>
51
52Returns 2 values: the width and height of the ''original'' image.
53
54<procedure>(image-file-output-set! img filename)</procedure>
55
56Set the output file for subsequent calls to {{image-encode}}.
57
58<procedure>(image-size-set! img width height)</procedure>
59
60Set the size of the new image, in pixels.  The original
61image is decoded into this size.
62
63<procedure>(image-bounds-set! img x y width height)</procedure>
64
65Set the bounds of the image to be decoded.  This is like cropping the
66image upon loading it.
67
68<procedure>(image-colorspace-set! img colorspace)</procedure>
69
70Set the colorspace for decoding.  This is one of the
71following:
72
73<constant>colorspace-gray8</constant>
74<constant>colorspace-yuv8</constant>
75<constant>colorspace-rgb8</constant>
76<constant>colorspace-bgr8</constant>
77<constant>colorspace-rgba8</constant>
78<constant>colorspace-bgra8</constant>
79<constant>colorspace-argb32</constant>
80<constant>colorspace-cmyk</constant>
81
82<procedure>(image-colorspace img) => colorspace</procedure>
83
84Returns the current colorspace value to use for decoding.
85The values returned by this is any of the constants
86described under {{image-colorspace-set!}}.
87
88<procedure>(image-comment-set! img comment)</procedure>
89
90Set the comment string for encoding.  By default, this is
91not written to the thumbnail! Use
92{{image-comment-enable}} to enable this.
93
94<procedure>(image-comment img) => string</procedure>
95
96Returns the comment string to use for encoding, or {{#f}} if none was set.
97
98<procedure>(image-comment-enable img)</procedure>
99
100Enable comment field for the thumbnail.
101
102<procedure>(image-comment-disable img)</procedure>
103
104Disable comment field for the thumbnail.  The default setting for
105comments is disabled.
106
107<procedure>(image-thumbnail-info img) => string string string string</procedure>
108
109Returns the 4 values: the uri field, width, height and mimetype of the
110thumbnail that will be written.
111
112<procedure>(image-quality-set! img percentage)</procedure>
113
114Set the thumbnail's image quality (0 - 100).
115
116<procedure>(image-trim img)</procedure>
117
118Undocumented.
119     
120==== Pixel query procedures
121
122Currently, the pixel query procedures are not available.
123
124=== Example
125
126What follows is an almost literal translation of src/bin/epeg_main.c
127from the epeg distribution tarball.
128
129<examples><example>
130<init>
131(use epeg)
132</init>
133<expr>
134(unless (= (length (argv)) 3)
135  (printf "Usage: ~A input.jpg thumb.jpg\n" (car (argv)))
136  (exit 0))
137
138; This will throw an i/o file exception if the file can't be opened
139(define im (image-open (list-ref (argv) 1)))
140
141(let ((com (image-comment im)))
142  (when com (printf "Comment: ~A\n" com)))
143
144(call-with-values
145    (lambda ()
146      (image-thumbnail-info im))
147  (lambda (uri width height mimetype)
148    (when mimetype
149          (printf "Thumb Mimetype: ~A\n" mimetype)
150          (when uri
151            (printf "Thumb URI: ~A\n" uri))
152          (printf "Thumb Mtime: \n")
153          (printf "Thumb Width: ~A\n" width)
154          (printf "Thumb Height: ~A\n" height))))
155
156(call-with-values
157    (lambda ()
158      (image-size im))
159  (lambda (width height)
160    (printf "Image size: ~Ax~A\n" width height)))
161
162(image-size-set! im 128 96)
163(image-quality-set! im 80)
164(image-comment-enable im)
165(image-comment-set! im "Smelly pants!")
166(image-file-output-set! im (list-ref (argv) 2))
167(image-encode im)
168(image-close im)  ; Not required, cleanup on GC
169
170(exit 0)
171</expr>
172
173=== Changelog
174
175* 2.2 Port to Chicken 4, renamed procedures and removed epeg: prefix, converted to wiki documentation
176* 2.1 Fix epeg:file-open failure when file not found
177* 2.0 Change API to use {{epeg:}} prefix for procedures. Change to eggdoc documentation format. Use GC finalizers.
178* 1.1 Added checks so (where it's possible) exceptions get thrown instead of segfaulting.
179* 1.0 initial release.
180
181=== License
182
183  Copyright (c) 2004-2008, Peter Bex
184  All rights reserved.
185 
186  Redistribution and use in source and binary forms, with or without
187  modification, are permitted provided that the following conditions are
188  met:
189 
190  Redistributions of source code must retain the above copyright
191  notice, this list of conditions and the following disclaimer.
192 
193  Redistributions in binary form must reproduce the above copyright
194  notice, this list of conditions and the following disclaimer in the
195  documentation and/or other materials provided with the distribution.
196 
197  Neither the name of the author nor the names of its contributors may
198  be used to endorse or promote products derived from this software
199  without specific prior written permission.
200 
201  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
202  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
203  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
204  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
205  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
206  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
207  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
208  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
209  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
210  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
211  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
212  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.