man/man3/FindPhoto.3 - toolchains/skids - Git at Google

 '\"
 '\" Copyright (c) 1994 The Australian National University
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
 '\" Author: Paul Mackerras (paulus@cs.anu.edu.au),
 '\"	    Department of Computer Science,
 '\"	    Australian National University.
 '\"
 '\" RCS: @(#) $Id: FindPhoto.3,v 1.6 2002/08/05 04:30:38 dgp Exp $
 '\"
 '\" The definitions below are for supplemental macros used in Tcl/Tk
 '\" manual entries.
 '\"
 '\" .AP type name in/out ?indent?
 '\"	Start paragraph describing an argument to a library procedure.
 '\"	type is type of argument (int, etc.), in/out is either "in", "out",
 '\"	or "in/out" to describe whether procedure reads or modifies arg,
 '\"	and indent is equivalent to second arg of .IP (shouldn't ever be
 '\"	needed;  use .AS below instead)
 '\"
 '\" .AS ?type? ?name?
 '\"	Give maximum sizes of arguments for setting tab stops.  Type and
 '\"	name are examples of largest possible arguments that will be passed
 '\"	to .AP later.  If args are omitted, default tab stops are used.
 '\"
 '\" .BS
 '\"	Start box enclosure.  From here until next .BE, everything will be
 '\"	enclosed in one large box.
 '\"
 '\" .BE
 '\"	End of box enclosure.
 '\"
 '\" .CS
 '\"	Begin code excerpt.
 '\"
 '\" .CE
 '\"	End code excerpt.
 '\"
 '\" .VS ?version? ?br?
 '\"	Begin vertical sidebar, for use in marking newly-changed parts
 '\"	of man pages.  The first argument is ignored and used for recording
 '\"	the version when the .VS was added, so that the sidebars can be
 '\"	found and removed when they reach a certain age.  If another argument
 '\"	is present, then a line break is forced before starting the sidebar.
 '\"
 '\" .VE
 '\"	End of vertical sidebar.
 '\"
 '\" .DS
 '\"	Begin an indented unfilled display.
 '\"
 '\" .DE
 '\"	End of indented unfilled display.
 '\"
 '\" .SO
 '\"	Start of list of standard options for a Tk widget.  The
 '\"	options follow on successive lines, in four columns separated
 '\"	by tabs.
 '\"
 '\" .SE
 '\"	End of list of standard options for a Tk widget.
 '\"
 '\" .OP cmdName dbName dbClass
 '\"	Start of description of a specific option.  cmdName gives the
 '\"	option's name as specified in the class command, dbName gives
 '\"	the option's name in the option database, and dbClass gives
 '\"	the option's class in the option database.
 '\"
 '\" .UL arg1 arg2
 '\"	Print arg1 underlined, then print arg2 normally.
 '\"
 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
 '\"
 '\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
 .if t .wh -1.3i ^B
 .nr ^l \n(.l
 .ad b
 '\"	# Start an argument description
 .de AP
 .ie !"\\$4"" .TP \\$4
 .el \{\
 .   ie !"\\$2"" .TP \\n()Cu
 .   el          .TP 15
 .\}
 .ta \\n()Au \\n()Bu
 .ie !"\\$3"" \{\
 \&\\$1	\\fI\\$2\\fP	(\\$3)
 .\".b
 .\}
 .el \{\
 .br
 .ie !"\\$2"" \{\
 \&\\$1	\\fI\\$2\\fP
 .\}
 .el \{\
 \&\\fI\\$1\\fP
 .\}
 .\}
 ..
 '\"	# define tabbing values for .AP
 .de AS
 .nr )A 10n
 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 .nr )B \\n()Au+15n
 .\"
 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 ..
 .AS Tcl_Interp Tcl_CreateInterp in/out
 '\"	# BS - start boxed text
 '\"	# ^y = starting y location
 '\"	# ^b = 1
 .de BS
 .br
 .mk ^y
 .nr ^b 1u
 .if n .nf
 .if n .ti 0
 .if n \l'\\n(.lu\(ul'
 .if n .fi
 ..
 '\"	# BE - end boxed text (draw box now)
 .de BE
 .nf
 .ti 0
 .mk ^t
 .ie n \l'\\n(^lu\(ul'
 .el \{\
 .\"	Draw four-sided box normally, but don't draw top of
 .\"	box if the box started on an earlier page.
 .ie !\\n(^b-1 \{\
 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 .\}
 .el \}\
 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 .\}
 .\}
 .fi
 .br
 .nr ^b 0
 ..
 '\"	# VS - start vertical sidebar
 '\"	# ^Y = starting y location
 '\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
 .de VS
 .if !"\\$2"" .br
 .mk ^Y
 .ie n 'mc \s12\(br\s0
 .el .nr ^v 1u
 ..
 '\"	# VE - end of vertical sidebar
 .de VE
 .ie n 'mc
 .el \{\
 .ev 2
 .nf
 .ti 0
 .mk ^t
 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 .sp -1
 .fi
 .ev
 .\}
 .nr ^v 0
 ..
 '\"	# Special macro to handle page bottom:  finish off current
 '\"	# box/sidebar if in box/sidebar mode, then invoked standard
 '\"	# page bottom macro.
 .de ^B
 .ev 2
 'ti 0
 'nf
 .mk ^t
 .if \\n(^b \{\
 .\"	Draw three-sided box if this is the box's first page,
 .\"	draw two sides but no top otherwise.
 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 .\}
 .if \\n(^v \{\
 .nr ^x \\n(^tu+1v-\\n(^Yu
 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 .\}
 .bp
 'fi
 .ev
 .if \\n(^b \{\
 .mk ^y
 .nr ^b 2
 .\}
 .if \\n(^v \{\
 .mk ^Y
 .\}
 ..
 '\"	# DS - begin display
 .de DS
 .RS
 .nf
 .sp
 ..
 '\"	# DE - end display
 .de DE
 .fi
 .RE
 .sp
 ..
 '\"	# SO - start of list of standard options
 .de SO
 .SH "STANDARD OPTIONS"
 .LP
 .nf
 .ta 5.5c 11c
 .ft B
 ..
 '\"	# SE - end of list of standard options
 .de SE
 .fi
 .ft R
 .LP
 See the \\fBoptions\\fR manual entry for details on the standard options.
 ..
 '\"	# OP - start of full description for a single option
 .de OP
 .LP
 .nf
 .ta 4c
 Command-Line Name:	\\fB\\$1\\fR
 Database Name:	\\fB\\$2\\fR
 Database Class:	\\fB\\$3\\fR
 .fi
 .IP
 ..
 '\"	# CS - begin code excerpt
 .de CS
 .RS
 .nf
 .ta .25i .5i .75i 1i
 ..
 '\"	# CE - end code excerpt
 .de CE
 .fi
 .RE
 ..
 .de UL
 \\$1\l'|0\(ul'\\$2
 ..
 .TH Tk_FindPhoto 3 8.0 Tk "Tk Library Procedures"
 .BS
 .SH NAME
 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.
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
 \fB#include <tkPhoto.h>\fR
 .sp
 Tk_PhotoHandle
 .VS 8.0 br
 \fBTk_FindPhoto\fR(\fIinterp, imageName\fR)
 .VE
 .sp
 void
 \fBTk_PhotoPutBlock\fR(\fIhandle, blockPtr, x, y, width, height, compRule\fR)
 .sp
 void
 \fBTk_PhotoPutZoomedBlock\fR(\fIhandle, blockPtr, x, y, width, height,\
 zoomX, zoomY, subsampleX, subsampleY, compRule\fR)
 .sp
 int
 \fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR)
 .sp
 void
 \fBTk_PhotoBlank\fR(\fIhandle\fR)
 .sp
 void
 \fBTk_PhotoExpand\fR(\fIhandle, width, height\fR)
 .sp
 void
 \fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR)
 .sp
 void
 \fBTk_PhotoSetSize\fR(\fIhandle, width, height\fR)
 .SH ARGUMENTS
 .AS Tk_PhotoImageBlock window_path
 .AP Tcl_Interp *interp in
 .VS
 Interpreter in which image was created.
 .VE
 .AP "CONST char" *imageName in
 Name of the photo image.
 .AP Tk_PhotoHandle handle in
 Opaque handle identifying the photo image to be affected.
 .AP Tk_PhotoImageBlock *blockPtr in
 Specifies the address and storage layout of image data.
 .AP int x in
 Specifies the X coordinate where the top-left corner of the block is
 to be placed within the image.
 .AP int y in
 Specifies the Y coordinate where the top-left corner of the block is
 to be placed within the image.
 .AP int width in
 Specifies the width of the image area to be affected (for
 \fBTk_PhotoPutBlock\fR) or the desired image width (for
 \fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR).
 .VS 8.4
 .AP int compRule in
 Specifies the compositing rule used when combining transparent pixels
 in a block of data with a photo image.  Must be one of
 TK_PHOTO_COMPOSITE_OVERLAY (which puts the block of data over the top
 of the existing photo image, with the previous contents showing
 through in the transparent bits) or TK_PHOTO_COMPOSITE_SET (which
 discards the existing photo image contents in the rectangle covered by
 the data block.)
 .VE 8.4
 .AP int height in
 Specifies the height of the image area to be affected (for
 \fBTk_PhotoPutBlock\fR) or the desired image height (for
 \fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR).
 .AP int *widthPtr out
 Pointer to location in which to store the image width.
 .AP int *heightPtr out
 Pointer to location in which to store the image height.
 .AP int subsampleX in
 Specifies the subsampling factor in the X direction for input
 image data.
 .AP int subsampleY in
 Specifies the subsampling factor in the Y direction for input
 image data.
 .AP int zoomX in
 Specifies the zoom factor to be applied in the X direction to pixels
 being written to the photo image.
 .AP int zoomY in
 Specifies the zoom factor to be applied in the Y direction to pixels
 being written to the photo image.
 .BE

 .SH DESCRIPTION
 .PP
 \fBTk_FindPhoto\fR returns an opaque handle that is used to identify a
 particular photo image to the other procedures.  The parameter is the
 name of the image, that is, the name specified to the \fBimage create
 photo\fR command, or assigned by that command if no name was specified.
 .PP
 \fBTk_PhotoPutBlock\fR is used to supply blocks of image data to be
 displayed.  The call affects an area of the image of size
 \fIwidth\fR x \fIheight\fR pixels, with its top-left corner at
 coordinates (\fIx\fR,\fIy\fR).  All of \fIwidth\fR, \fIheight\fR,
 \fIx\fR, and \fIy\fR must be non-negative.
 If part of this area lies outside the
 current bounds of the image, the image will be expanded to include the
 area, unless the user has specified an explicit image size with the
 \fB\-width\fR and/or \fB\-height\fR widget configuration options
 (see photo(n)); in that
 case the area is silently clipped to the image boundaries.
 .PP
 The \fIblock\fR parameter is a pointer to a
 \fBTk_PhotoImageBlock\fR structure, defined as follows:
 .CS
 typedef struct {
 	unsigned char *\fIpixelPtr\fR;
 	int \fIwidth\fR;
 	int \fIheight\fR;
 	int \fIpitch\fR;
 	int \fIpixelSize\fR;
 	int \fIoffset[4]\fR;
 } Tk_PhotoImageBlock;
 .CE
 The \fIpixelPtr\fR field points to the first pixel, that is, the
 top-left pixel in the block.
 The \fIwidth\fR and \fIheight\fR fields specify the dimensions of the
 block of pixels.  The \fIpixelSize\fR field specifies the address
 difference between two horizontally adjacent pixels.  Often it is 3
 or 4, but it can have any value.  The \fIpitch\fR field specifies the
 address difference between two vertically adjacent pixels.  The
 \fIoffset\fR array contains the offsets from the address of a pixel
 to the addresses of the bytes containing the red, green, blue and alpha
 (transparency) components.  These are normally 0, 1, 2 and 3, but can
 have other values, e.g., for images that are stored as separate red,
 green and blue planes.
 .PP
 .VS 8.4
 The \fIcompRule\fR parameter to \fBTk_PhotoPutBlock\fR specifies a
 compositing rule that says what to do with transparent pixels.  The
 value TK_PHOTO_COMPOSITE_OVERLAY says that the previous contents of
 the photo image should show through, and the value
 TK_PHOTO_COMPOSITE_SET says that the previous contents of the photo
 image should be completely ignored, and the values from the block be
 copied directly across.  The behavior in Tk8.3 and earlier was
 equivalent to having TK_PHOTO_COMPOSITE_OVERLAY as a compositing rule.
 .VE 8.4
 .PP
 The value given for the \fIwidth\fR and \fIheight\fR parameters to
 \fBTk_PhotoPutBlock\fR do not have to correspond to the values specified
 in \fIblock\fR.  If they are smaller, \fBTk_PhotoPutBlock\fR extracts a
 sub-block from the image data supplied.  If they are larger, the data
 given are replicated (in a tiled fashion) to fill the specified area.
 These rules operate independently in the horizontal and vertical
 directions.
 .PP
 \fBTk_PhotoPutZoomedBlock\fR works like \fBTk_PhotoPutBlock\fR except that
 the image can be reduced or enlarged for display.  The
 \fIsubsampleX\fR and \fIsubsampleY\fR parameters allow the size of the
 image to be reduced by subsampling.
 \fBTk_PhotoPutZoomedBlock\fR will use only pixels from the input image
 whose X coordinates are multiples of \fIsubsampleX\fR, and whose Y
 coordinates are multiples of \fIsubsampleY\fR.  For example, an image
 of 512x512 pixels can be reduced to 256x256 by setting
 \fIsubsampleX\fR and \fIsubsampleY\fR to 2.
 .PP
 The \fIzoomX\fR and \fIzoomY\fR parameters allow the image to be
 enlarged by pixel replication.  Each pixel of the (possibly subsampled)
 input image will be written to a block \fIzoomX\fR pixels wide and
 \fIzoomY\fR pixels high of the displayed image.  Subsampling and
 zooming can be used together for special effects.
 .PP
 \fBTk_PhotoGetImage\fR can be used to retrieve image data from a photo
 image.  \fBTk_PhotoGetImage\fR fills
 in the structure pointed to by the \fIblockPtr\fR parameter with values
 that describe the address and layout of the image data that the
 photo image has stored internally.  The values are valid
 until the image is destroyed or its size is changed.
 \fBTk_PhotoGetImage\fR returns 1 for compatibility with the
 corresponding procedure in the old photo widget.
 .PP
 \fBTk_PhotoBlank\fR blanks the entire area of the
 photo image.  Blank areas of a photo image are transparent.
 .PP
 \fBTk_PhotoExpand\fR requests that the widget's image be expanded to be
 at least \fIwidth\fR x \fIheight\fR pixels in size.  The width and/or
 height are unchanged if the user has specified an explicit image width
 or height with the \fB\-width\fR and/or \fB\-height\fR configuration
 options, respectively.
 If the image data
 are being supplied in many small blocks, it is more efficient to use
 \fBTk_PhotoExpand\fR or \fBTk_PhotoSetSize\fR at the beginning rather than
 allowing the image to expand in many small increments as image blocks
 are supplied.
 .PP
 \fBTk_PhotoSetSize\fR specifies the size of the image, as if the user
 had specified the given \fIwidth\fR and \fIheight\fR values to the
 \fB\-width\fR and \fB\-height\fR configuration options.  A value of
 zero for \fIwidth\fR or \fIheight\fR does not change the image's width
 or height, but allows the width or height to be changed by subsequent
 calls to \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR or
 \fBTk_PhotoExpand\fR.
 .PP
 \fBTk_PhotoGetSize\fR returns the dimensions of the image in
 *\fIwidthPtr\fR and *\fIheightPtr\fR.

 .SH PORTABILITY
 .VS 8.4
 .PP
 In Tk 8.3 and earlier, \fBTk_PhotoPutBlock\fR and
 \fBTk_PhotoPutZoomedBlock\fR had different signatures. If you want to
 compile code that uses the old interface against 8.4 without updating
 your code, compile it with the flag
 -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK.  Code linked using Stubs against
 older versions of Tk will continue to work.
 .VE 8.4

 .SH CREDITS
 .PP
 The code for the photo image type was developed by Paul Mackerras,
 based on his earlier photo widget code.

 .SH KEYWORDS
 photo, image
	'\"
	'\" Copyright (c) 1994 The Australian National University
	'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
	'\"
	'\" See the file "license.terms" for information on usage and redistribution
	'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
	'\"
	'\" Author: Paul Mackerras (paulus@cs.anu.edu.au),
	'\" Department of Computer Science,
	'\" Australian National University.
	'\"
	'\" RCS: @(#) $Id: FindPhoto.3,v 1.6 2002/08/05 04:30:38 dgp Exp $
	'\"
	'\" The definitions below are for supplemental macros used in Tcl/Tk
	'\" manual entries.
	'\"
	'\" .AP type name in/out ?indent?
	'\" Start paragraph describing an argument to a library procedure.
	'\" type is type of argument (int, etc.), in/out is either "in", "out",
	'\" or "in/out" to describe whether procedure reads or modifies arg,
	'\" and indent is equivalent to second arg of .IP (shouldn't ever be
	'\" needed; use .AS below instead)
	'\"
	'\" .AS ?type? ?name?
	'\" Give maximum sizes of arguments for setting tab stops. Type and
	'\" name are examples of largest possible arguments that will be passed
	'\" to .AP later. If args are omitted, default tab stops are used.
	'\"
	'\" .BS
	'\" Start box enclosure. From here until next .BE, everything will be
	'\" enclosed in one large box.
	'\"
	'\" .BE
	'\" End of box enclosure.
	'\"
	'\" .CS
	'\" Begin code excerpt.
	'\"
	'\" .CE
	'\" End code excerpt.
	'\"
	'\" .VS ?version? ?br?
	'\" Begin vertical sidebar, for use in marking newly-changed parts
	'\" of man pages. The first argument is ignored and used for recording
	'\" the version when the .VS was added, so that the sidebars can be
	'\" found and removed when they reach a certain age. If another argument
	'\" is present, then a line break is forced before starting the sidebar.
	'\"
	'\" .VE
	'\" End of vertical sidebar.
	'\"
	'\" .DS
	'\" Begin an indented unfilled display.
	'\"
	'\" .DE
	'\" End of indented unfilled display.
	'\"
	'\" .SO
	'\" Start of list of standard options for a Tk widget. The
	'\" options follow on successive lines, in four columns separated
	'\" by tabs.
	'\"
	'\" .SE
	'\" End of list of standard options for a Tk widget.
	'\"
	'\" .OP cmdName dbName dbClass
	'\" Start of description of a specific option. cmdName gives the
	'\" option's name as specified in the class command, dbName gives
	'\" the option's name in the option database, and dbClass gives
	'\" the option's class in the option database.
	'\"
	'\" .UL arg1 arg2
	'\" Print arg1 underlined, then print arg2 normally.
	'\"
	'\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
	'\"
	'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
	.if t .wh -1.3i ^B
	.nr ^l \n(.l
	.ad b
	'\" # Start an argument description
	.de AP
	.ie !"\\$4"" .TP \\$4
	.el \{\
	. ie !"\\$2"" .TP \\n()Cu
	. el .TP 15
	.\}
	.ta \\n()Au \\n()Bu
	.ie !"\\$3"" \{\
	\&\\$1 \\fI\\$2\\fP (\\$3)
	.\".b
	.\}
	.el \{\
	.br
	.ie !"\\$2"" \{\
	\&\\$1 \\fI\\$2\\fP
	.\}
	.el \{\
	\&\\fI\\$1\\fP
	.\}
	.\}
	..
	'\" # define tabbing values for .AP
	.de AS
	.nr )A 10n
	.if !"\\$1"" .nr )A \\w'\\$1'u+3n
	.nr )B \\n()Au+15n
	.\"
	.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
	.nr )C \\n()Bu+\\w'(in/out)'u+2n
	..
	.AS Tcl_Interp Tcl_CreateInterp in/out
	'\" # BS - start boxed text
	'\" # ^y = starting y location
	'\" # ^b = 1
	.de BS
	.br
	.mk ^y
	.nr ^b 1u
	.if n .nf
	.if n .ti 0
	.if n \l'\\n(.lu\(ul'
	.if n .fi
	..
	'\" # BE - end boxed text (draw box now)
	.de BE
	.nf
	.ti 0
	.mk ^t
	.ie n \l'\\n(^lu\(ul'
	.el \{\
	.\" Draw four-sided box normally, but don't draw top of
	.\" box if the box started on an earlier page.
	.ie !\\n(^b-1 \{\
	\h'-1.5n'\L'\|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'\|0u-1.5n\(ul'
	.\}
	.el \}\
	\h'-1.5n'\L'\|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'\|0u-1.5n\(ul'
	.\}
	.\}
	.fi
	.br
	.nr ^b 0
	..
	'\" # VS - start vertical sidebar
	'\" # ^Y = starting y location
	'\" # ^v = 1 (for troff; for nroff this doesn't matter)
	.de VS
	.if !"\\$2"" .br
	.mk ^Y
	.ie n 'mc \s12\(br\s0
	.el .nr ^v 1u
	..
	'\" # VE - end of vertical sidebar
	.de VE
	.ie n 'mc
	.el \{\
	.ev 2
	.nf
	.ti 0
	.mk ^t
	\h'\|\\n(^lu+3n'\L'\|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-\|\\n(^lu+3n'
	.sp -1
	.fi
	.ev
	.\}
	.nr ^v 0
	..
	'\" # Special macro to handle page bottom: finish off current
	'\" # box/sidebar if in box/sidebar mode, then invoked standard
	'\" # page bottom macro.
	.de ^B
	.ev 2
	'ti 0
	'nf
	.mk ^t
	.if \\n(^b \{\
	.\" Draw three-sided box if this is the box's first page,
	.\" draw two sides but no top otherwise.
	.ie !\\n(^b-1 \h'-1.5n'\L'\|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'\|0u'\c
	.el \h'-1.5n'\L'\|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'\|0u'\c
	.\}
	.if \\n(^v \{\
	.nr ^x \\n(^tu+1v-\\n(^Yu
	\kx\h'-\\nxu'\h'\|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'\|0u'\c
	.\}
	.bp
	'fi
	.ev
	.if \\n(^b \{\
	.mk ^y
	.nr ^b 2
	.\}
	.if \\n(^v \{\
	.mk ^Y
	.\}
	..
	'\" # DS - begin display
	.de DS
	.RS
	.nf
	.sp
	..
	'\" # DE - end display
	.de DE
	.fi
	.RE
	.sp
	..
	'\" # SO - start of list of standard options
	.de SO
	.SH "STANDARD OPTIONS"
	.LP
	.nf
	.ta 5.5c 11c
	.ft B
	..
	'\" # SE - end of list of standard options
	.de SE
	.fi
	.ft R
	.LP
	See the \\fBoptions\\fR manual entry for details on the standard options.
	..
	'\" # OP - start of full description for a single option
	.de OP
	.LP
	.nf
	.ta 4c
	Command-Line Name: \\fB\\$1\\fR
	Database Name: \\fB\\$2\\fR
	Database Class: \\fB\\$3\\fR
	.fi
	.IP
	..
	'\" # CS - begin code excerpt
	.de CS
	.RS
	.nf
	.ta .25i .5i .75i 1i
	..
	'\" # CE - end code excerpt
	.de CE
	.fi
	.RE
	..
	.de UL
	\\$1\l'\|0\(ul'\\$2
	..
	.TH Tk_FindPhoto 3 8.0 Tk "Tk Library Procedures"
	.BS
	.SH NAME
	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.
	.SH SYNOPSIS
	.nf
	\fB#include <tk.h>\fR
	\fB#include <tkPhoto.h>\fR
	.sp
	Tk_PhotoHandle
	.VS 8.0 br
	\fBTk_FindPhoto\fR(\fIinterp, imageName\fR)
	.VE
	.sp
	void
	\fBTk_PhotoPutBlock\fR(\fIhandle, blockPtr, x, y, width, height, compRule\fR)
	.sp
	void
	\fBTk_PhotoPutZoomedBlock\fR(\fIhandle, blockPtr, x, y, width, height,\
	zoomX, zoomY, subsampleX, subsampleY, compRule\fR)
	.sp
	int
	\fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR)
	.sp
	void
	\fBTk_PhotoBlank\fR(\fIhandle\fR)
	.sp
	void
	\fBTk_PhotoExpand\fR(\fIhandle, width, height\fR)
	.sp
	void
	\fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR)
	.sp
	void
	\fBTk_PhotoSetSize\fR(\fIhandle, width, height\fR)
	.SH ARGUMENTS
	.AS Tk_PhotoImageBlock window_path
	.AP Tcl_Interp *interp in
	.VS
	Interpreter in which image was created.
	.VE
	.AP "CONST char" *imageName in
	Name of the photo image.
	.AP Tk_PhotoHandle handle in
	Opaque handle identifying the photo image to be affected.
	.AP Tk_PhotoImageBlock *blockPtr in
	Specifies the address and storage layout of image data.
	.AP int x in
	Specifies the X coordinate where the top-left corner of the block is
	to be placed within the image.
	.AP int y in
	Specifies the Y coordinate where the top-left corner of the block is
	to be placed within the image.
	.AP int width in
	Specifies the width of the image area to be affected (for
	\fBTk_PhotoPutBlock\fR) or the desired image width (for
	\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR).
	.VS 8.4
	.AP int compRule in
	Specifies the compositing rule used when combining transparent pixels
	in a block of data with a photo image. Must be one of
	TK_PHOTO_COMPOSITE_OVERLAY (which puts the block of data over the top
	of the existing photo image, with the previous contents showing
	through in the transparent bits) or TK_PHOTO_COMPOSITE_SET (which
	discards the existing photo image contents in the rectangle covered by
	the data block.)
	.VE 8.4
	.AP int height in
	Specifies the height of the image area to be affected (for
	\fBTk_PhotoPutBlock\fR) or the desired image height (for
	\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR).
	.AP int *widthPtr out
	Pointer to location in which to store the image width.
	.AP int *heightPtr out
	Pointer to location in which to store the image height.
	.AP int subsampleX in
	Specifies the subsampling factor in the X direction for input
	image data.
	.AP int subsampleY in
	Specifies the subsampling factor in the Y direction for input
	image data.
	.AP int zoomX in
	Specifies the zoom factor to be applied in the X direction to pixels
	being written to the photo image.
	.AP int zoomY in
	Specifies the zoom factor to be applied in the Y direction to pixels
	being written to the photo image.
	.BE

	.SH DESCRIPTION
	.PP
	\fBTk_FindPhoto\fR returns an opaque handle that is used to identify a
	particular photo image to the other procedures. The parameter is the
	name of the image, that is, the name specified to the \fBimage create
	photo\fR command, or assigned by that command if no name was specified.
	.PP
	\fBTk_PhotoPutBlock\fR is used to supply blocks of image data to be
	displayed. The call affects an area of the image of size
	\fIwidth\fR x \fIheight\fR pixels, with its top-left corner at
	coordinates (\fIx\fR,\fIy\fR). All of \fIwidth\fR, \fIheight\fR,
	\fIx\fR, and \fIy\fR must be non-negative.
	If part of this area lies outside the
	current bounds of the image, the image will be expanded to include the
	area, unless the user has specified an explicit image size with the
	\fB\-width\fR and/or \fB\-height\fR widget configuration options
	(see photo(n)); in that
	case the area is silently clipped to the image boundaries.
	.PP
	The \fIblock\fR parameter is a pointer to a
	\fBTk_PhotoImageBlock\fR structure, defined as follows:
	.CS
	typedef struct {
	unsigned char *\fIpixelPtr\fR;
	int \fIwidth\fR;
	int \fIheight\fR;
	int \fIpitch\fR;
	int \fIpixelSize\fR;
	int \fIoffset[4]\fR;
	} Tk_PhotoImageBlock;
	.CE
	The \fIpixelPtr\fR field points to the first pixel, that is, the
	top-left pixel in the block.
	The \fIwidth\fR and \fIheight\fR fields specify the dimensions of the
	block of pixels. The \fIpixelSize\fR field specifies the address
	difference between two horizontally adjacent pixels. Often it is 3
	or 4, but it can have any value. The \fIpitch\fR field specifies the
	address difference between two vertically adjacent pixels. The
	\fIoffset\fR array contains the offsets from the address of a pixel
	to the addresses of the bytes containing the red, green, blue and alpha
	(transparency) components. These are normally 0, 1, 2 and 3, but can
	have other values, e.g., for images that are stored as separate red,
	green and blue planes.
	.PP
	.VS 8.4
	The \fIcompRule\fR parameter to \fBTk_PhotoPutBlock\fR specifies a
	compositing rule that says what to do with transparent pixels. The
	value TK_PHOTO_COMPOSITE_OVERLAY says that the previous contents of
	the photo image should show through, and the value
	TK_PHOTO_COMPOSITE_SET says that the previous contents of the photo
	image should be completely ignored, and the values from the block be
	copied directly across. The behavior in Tk8.3 and earlier was
	equivalent to having TK_PHOTO_COMPOSITE_OVERLAY as a compositing rule.
	.VE 8.4
	.PP
	The value given for the \fIwidth\fR and \fIheight\fR parameters to
	\fBTk_PhotoPutBlock\fR do not have to correspond to the values specified
	in \fIblock\fR. If they are smaller, \fBTk_PhotoPutBlock\fR extracts a
	sub-block from the image data supplied. If they are larger, the data
	given are replicated (in a tiled fashion) to fill the specified area.
	These rules operate independently in the horizontal and vertical
	directions.
	.PP
	\fBTk_PhotoPutZoomedBlock\fR works like \fBTk_PhotoPutBlock\fR except that
	the image can be reduced or enlarged for display. The
	\fIsubsampleX\fR and \fIsubsampleY\fR parameters allow the size of the
	image to be reduced by subsampling.
	\fBTk_PhotoPutZoomedBlock\fR will use only pixels from the input image
	whose X coordinates are multiples of \fIsubsampleX\fR, and whose Y
	coordinates are multiples of \fIsubsampleY\fR. For example, an image
	of 512x512 pixels can be reduced to 256x256 by setting
	\fIsubsampleX\fR and \fIsubsampleY\fR to 2.
	.PP
	The \fIzoomX\fR and \fIzoomY\fR parameters allow the image to be
	enlarged by pixel replication. Each pixel of the (possibly subsampled)
	input image will be written to a block \fIzoomX\fR pixels wide and
	\fIzoomY\fR pixels high of the displayed image. Subsampling and
	zooming can be used together for special effects.
	.PP
	\fBTk_PhotoGetImage\fR can be used to retrieve image data from a photo
	image. \fBTk_PhotoGetImage\fR fills
	in the structure pointed to by the \fIblockPtr\fR parameter with values
	that describe the address and layout of the image data that the
	photo image has stored internally. The values are valid
	until the image is destroyed or its size is changed.
	\fBTk_PhotoGetImage\fR returns 1 for compatibility with the
	corresponding procedure in the old photo widget.
	.PP
	\fBTk_PhotoBlank\fR blanks the entire area of the
	photo image. Blank areas of a photo image are transparent.
	.PP
	\fBTk_PhotoExpand\fR requests that the widget's image be expanded to be
	at least \fIwidth\fR x \fIheight\fR pixels in size. The width and/or
	height are unchanged if the user has specified an explicit image width
	or height with the \fB\-width\fR and/or \fB\-height\fR configuration
	options, respectively.
	If the image data
	are being supplied in many small blocks, it is more efficient to use
	\fBTk_PhotoExpand\fR or \fBTk_PhotoSetSize\fR at the beginning rather than
	allowing the image to expand in many small increments as image blocks
	are supplied.
	.PP
	\fBTk_PhotoSetSize\fR specifies the size of the image, as if the user
	had specified the given \fIwidth\fR and \fIheight\fR values to the
	\fB\-width\fR and \fB\-height\fR configuration options. A value of
	zero for \fIwidth\fR or \fIheight\fR does not change the image's width
	or height, but allows the width or height to be changed by subsequent
	calls to \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR or
	\fBTk_PhotoExpand\fR.
	.PP
	\fBTk_PhotoGetSize\fR returns the dimensions of the image in
	\fIwidthPtr\fR and \fIheightPtr\fR.

	.SH PORTABILITY
	.VS 8.4
	.PP
	In Tk 8.3 and earlier, \fBTk_PhotoPutBlock\fR and
	\fBTk_PhotoPutZoomedBlock\fR had different signatures. If you want to
	compile code that uses the old interface against 8.4 without updating
	your code, compile it with the flag
	-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK. Code linked using Stubs against
	older versions of Tk will continue to work.
	.VE 8.4

	.SH CREDITS
	.PP
	The code for the photo image type was developed by Paul Mackerras,
	based on his earlier photo widget code.

	.SH KEYWORDS
	photo, image