1#  Copyright (c) 1994 The Australian National University
2#  Copyright (c) 1994-1996 Sun Microsystems, Inc.
3#  See the file "license.terms" for information on usage and redistribution
4#  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
5#
6#  Author: Paul Mackerras (paulus@cs.anu.edu.au),
7# 	    Department of Computer Science,
8# 	    Australian National University.
9#  "@(#) FindPhoto.3 1.11 97/08/22 18:52:33"
10
11=head1 NAME
12
13Tk_FindPhoto, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetImage, Tk_PhotoBlank, Tk_PhotoExpand, Tk_PhotoGetSize, Tk_PhotoSetSize - manipulate the image data stored in a photo image.
14
15=for category C Programming
16
17=head1 SYNOPSIS
18
19B<#include E<lt>tk.hE<gt>>
20B<#include E<lt>tkPhoto.hE<gt>>
21
22Tk_PhotoHandle
23B<Tk_FindPhoto>(I<interp, imageName>)
24
25void
26B<Tk_PhotoPutBlock>(I<handle, blockPtr, x, y, width, height>)
27
28void
29B<Tk_PhotoPutZoomedBlock>(I<handle, blockPtr, x, y, width, height,\>
30zoomX, zoomY, subsampleX, subsampleY)
31
32int
33B<Tk_PhotoGetImage>(I<handle, blockPtr>)
34
35void
36B<Tk_PhotoBlank>(I<handle>)
37
38void
39B<Tk_PhotoExpand>(I<handle, width, height>)
40
41void
42B<Tk_PhotoGetSize>(I<handle, widthPtr, heightPtr>)
43
44void
45B<Tk_PhotoSetSize>(I<handle, width, height>)
46
47=head1 ARGUMENTS
48
49=over 4
50
51=item Tcl_Interp *interp (in)
52
53Interpreter in which image was created.
54
55=item char *imageName (in)
56
57Name of the photo image.
58
59=item Tk_PhotoHandle handle (in)
60
61Opaque handle identifying the photo image to be affected.
62
63=item Tk_PhotoImageBlock *blockPtr (in)
64
65Specifies the address and storage layout of image data.
66
67=item int x (in)
68
69Specifies the X coordinate where the top-left corner of the block is
70to be placed within the image.
71
72=item int y (in)
73
74Specifies the Y coordinate where the top-left corner of the block is
75to be placed within the image.
76
77=item int width (in)
78
79Specifies the width of the image area to be affected (for
80B<Tk_PhotoPutBlock>) or the desired image width (for
81B<Tk_PhotoExpand> and B<Tk_PhotoSetSize>).
82
83=item int height (in)
84
85Specifies the height of the image area to be affected (for
86B<Tk_PhotoPutBlock>) or the desired image height (for
87B<Tk_PhotoExpand> and B<Tk_PhotoSetSize>).
88
89=item int *widthPtr (out)
90
91Pointer to location in which to store the image width.
92
93=item int *heightPtr (out)
94
95Pointer to location in which to store the image height.
96
97=item int subsampleX (in)
98
99Specifies the subsampling factor in the X direction for input
100image data.
101
102=item int subsampleY (in)
103
104Specifies the subsampling factor in the Y direction for input
105image data.
106
107=item int zoomX (in)
108
109Specifies the zoom factor to be applied in the X direction to pixels
110being written to the photo image.
111
112=item int zoomY (in)
113
114Specifies the zoom factor to be applied in the Y direction to pixels
115being written to the photo image.
116
117=back
118
119=head1 DESCRIPTION
120
121B<Tk_FindPhoto> returns an opaque handle that is used to identify a
122particular photo image to the other procedures.  The parameter is the
123name of the image, that is, the name specified to the B<image create>
124photo command, or assigned by that command if no name was specified.
125
126B<Tk_PhotoPutBlock> is used to supply blocks of image data to be
127displayed.  The call affects an area of the image of size
128I<width> x I<height> pixels, with its top-left corner at
129coordinates (I<x>,I<y>).  All of I<width>, I<height>,
130I<x>, and I<y> must be non-negative.
131If part of this area lies outside the
132current bounds of the image, the image will be expanded to include the
133area, unless the user has specified an explicit image size with the
134B<-width> and/or B<-height> widget configuration options
135(see photo(n)); in that
136case the area is silently clipped to the image boundaries.
137
138The I<block> parameter is a pointer to a
139B<Tk_PhotoImageBlock> structure, defined as follows:
140
141 typedef struct {
142 	unsigned char *pixelPtr;
143 	int width;
144 	int height;
145 	int pitch;
146 	int pixelSize;
147 	int offset[3];
148 } Tk_PhotoImageBlock;
149
150The I<pixelPtr> field points to the first pixel, that is, the
151top-left pixel in the block.
152The I<width> and I<height> fields specify the dimensions of the
153block of pixels.  The I<pixelSize> field specifies the address
154difference between two horizontally adjacent pixels.  Often it is 3
155or 4, but it can have any value.  The I<pitch> field specifies the
156address difference between two vertically adjacent pixels.  The
157I<offset> array contains the offsets from the address of a pixel
158to the addresses of the bytes containing the red, green and blue
159components.  These are normally 0, 1 and 2, but can have other values,
160e.g., for images that are stored as separate red, green and blue
161planes.
162
163The value given for the I<width> and I<height> parameters to
164B<Tk_PhotoPutBlock> do not have to correspond to the values specified
165in I<block>.  If they are smaller, B<Tk_PhotoPutBlock> extracts a
166sub-block from the image data supplied.  If they are larger, the data
167given are replicated (in a tiled fashion) to fill the specified area.
168These rules operate independently in the horizontal and vertical
169directions.
170
171B<Tk_PhotoPutZoomedBlock> works like B<Tk_PhotoPutBlock> except that
172the image can be reduced or enlarged for display.  The
173I<subsampleX> and I<subsampleY> parameters allow the size of the
174image to be reduced by subsampling.
175B<Tk_PhotoPutZoomedBlock> will use only pixels from the input image
176whose X coordinates are multiples of I<subsampleX>, and whose Y
177coordinates are multiples of I<subsampleY>.  For example, an image
178of 512x512 pixels can be reduced to 256x256 by setting
179I<subsampleX> and I<subsampleY> to 2.
180
181The I<zoomX> and I<zoomY> parameters allow the image to be
182enlarged by pixel replication.  Each pixel of the (possibly subsampled)
183input image will be written to a block I<zoomX> pixels wide and
184I<zoomY> pixels high of the displayed image.  Subsampling and
185zooming can be used together for special effects.
186
187B<Tk_PhotoGetImage> can be used to retrieve image data from a photo
188image.  B<Tk_PhotoGetImage> fills
189in the structure pointed to by the I<blockPtr> parameter with values
190that describe the address and layout of the image data that the
191photo image has stored internally.  The values are valid
192until the image is destroyed or its size is changed.
193B<Tk_PhotoGetImage> returns 1 for compatibility with the
194corresponding procedure in the old photo widget.
195
196B<Tk_PhotoBlank> blanks the entire area of the
197photo image.  Blank areas of a photo image are transparent.
198
199B<Tk_PhotoExpand> requests that the widget's image be expanded to be
200at least I<width> x I<height> pixels in size.  The width and/or
201height are unchanged if the user has specified an explicit image width
202or height with the B<-width> and/or B<-height> configuration
203options, respectively.
204If the image data
205are being supplied in many small blocks, it is more efficient to use
206B<Tk_PhotoExpand> or B<Tk_PhotoSetSize> at the beginning rather than
207allowing the image to expand in many small increments as image blocks
208are supplied.
209
210B<Tk_PhotoSetSize> specifies the size of the image, as if the user
211had specified the given I<width> and I<height> values to the
212B<-width> and B<-height> configuration options.  A value of
213zero for I<width> or I<height> does not change the image's width
214or height, but allows the width or height to be changed by subsequent
215calls to B<Tk_PhotoPutBlock>, B<Tk_PhotoPutZoomedBlock> or
216B<Tk_PhotoExpand>.
217
218B<Tk_PhotoGetSize> returns the dimensions of the image in
219*I<widthPtr> and *I<heightPtr>.
220
221=head1 CREDITS
222
223The code for the photo image type was developed by Paul Mackerras,
224based on his earlier photo widget code.
225
226=head1 KEYWORDS
227
228photo, image
229