tk/doc/FindPhoto.3

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