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

Last change on this file since 12880 was 12880, checked in by sjamaan, 12 years ago

Temporary hack to fix example sections in wiki eggdoc pages

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