0000: 27 5c 22 0a 27 5c 22 20 43 6f 70 79 72 69 67 68 '\".'\" Copyrigh
0010: 74 20 28 63 29 20 31 39 39 34 20 54 68 65 20 41 t (c) 1994 The A
0020: 75 73 74 72 61 6c 69 61 6e 20 4e 61 74 69 6f 6e ustralian Nation
0030: 61 6c 20 55 6e 69 76 65 72 73 69 74 79 0a 27 5c al University.'\
0040: 22 20 43 6f 70 79 72 69 67 68 74 20 28 63 29 20 " Copyright (c)
0050: 31 39 39 34 2d 31 39 39 36 20 53 75 6e 20 4d 69 1994-1996 Sun Mi
0060: 63 72 6f 73 79 73 74 65 6d 73 2c 20 49 6e 63 2e crosystems, Inc.
0070: 0a 27 5c 22 0a 27 5c 22 20 53 65 65 20 74 68 65 .'\".'\" See the
0080: 20 66 69 6c 65 20 22 6c 69 63 65 6e 73 65 2e 74 file "license.t
0090: 65 72 6d 73 22 20 66 6f 72 20 69 6e 66 6f 72 6d erms" for inform
00a0: 61 74 69 6f 6e 20 6f 6e 20 75 73 61 67 65 20 61 ation on usage a
00b0: 6e 64 20 72 65 64 69 73 74 72 69 62 75 74 69 6f nd redistributio
00c0: 6e 0a 27 5c 22 20 6f 66 20 74 68 69 73 20 66 69 n.'\" of this fi
00d0: 6c 65 2c 20 61 6e 64 20 66 6f 72 20 61 20 44 49 le, and for a DI
00e0: 53 43 4c 41 49 4d 45 52 20 4f 46 20 41 4c 4c 20 SCLAIMER OF ALL
00f0: 57 41 52 52 41 4e 54 49 45 53 2e 0a 27 5c 22 0a WARRANTIES..'\".
0100: 27 5c 22 20 41 75 74 68 6f 72 3a 20 50 61 75 6c '\" Author: Paul
0110: 20 4d 61 63 6b 65 72 72 61 73 20 28 70 61 75 6c Mackerras (paul
0120: 75 73 40 63 73 2e 61 6e 75 2e 65 64 75 2e 61 75 [email protected]
0130: 29 2c 0a 27 5c 22 09 20 20 20 20 44 65 70 61 72 ),.'\". Depar
0140: 74 6d 65 6e 74 20 6f 66 20 43 6f 6d 70 75 74 65 tment of Compute
0150: 72 20 53 63 69 65 6e 63 65 2c 0a 27 5c 22 09 20 r Science,.'\".
0160: 20 20 20 41 75 73 74 72 61 6c 69 61 6e 20 4e 61 Australian Na
0170: 74 69 6f 6e 61 6c 20 55 6e 69 76 65 72 73 69 74 tional Universit
0180: 79 2e 0a 27 5c 22 0a 2e 54 48 20 54 6b 5f 46 69 y..'\"..TH Tk_Fi
0190: 6e 64 50 68 6f 74 6f 20 33 20 38 2e 30 20 54 6b ndPhoto 3 8.0 Tk
01a0: 20 22 54 6b 20 4c 69 62 72 61 72 79 20 50 72 6f "Tk Library Pro
01b0: 63 65 64 75 72 65 73 22 0a 2e 73 6f 20 6d 61 6e cedures"..so man
01c0: 2e 6d 61 63 72 6f 73 0a 2e 42 53 0a 2e 53 48 20 .macros..BS..SH
01d0: 4e 41 4d 45 0a 54 6b 5f 46 69 6e 64 50 68 6f 74 NAME.Tk_FindPhot
01e0: 6f 2c 20 54 6b 5f 50 68 6f 74 6f 50 75 74 42 6c o, Tk_PhotoPutBl
01f0: 6f 63 6b 2c 20 54 6b 5f 50 68 6f 74 6f 50 75 74 ock, Tk_PhotoPut
0200: 5a 6f 6f 6d 65 64 42 6c 6f 63 6b 2c 20 54 6b 5f ZoomedBlock, Tk_
0210: 50 68 6f 74 6f 47 65 74 49 6d 61 67 65 2c 20 54 PhotoGetImage, T
0220: 6b 5f 50 68 6f 74 6f 42 6c 61 6e 6b 2c 20 54 6b k_PhotoBlank, Tk
0230: 5f 50 68 6f 74 6f 45 78 70 61 6e 64 2c 20 54 6b _PhotoExpand, Tk
0240: 5f 50 68 6f 74 6f 47 65 74 53 69 7a 65 2c 20 54 _PhotoGetSize, T
0250: 6b 5f 50 68 6f 74 6f 53 65 74 53 69 7a 65 20 5c k_PhotoSetSize \
0260: 2d 20 6d 61 6e 69 70 75 6c 61 74 65 20 74 68 65 - manipulate the
0270: 20 69 6d 61 67 65 20 64 61 74 61 20 73 74 6f 72 image data stor
0280: 65 64 20 69 6e 20 61 20 70 68 6f 74 6f 20 69 6d ed in a photo im
0290: 61 67 65 2e 0a 2e 53 48 20 53 59 4e 4f 50 53 49 age...SH SYNOPSI
02a0: 53 0a 2e 6e 66 0a 5c 66 42 23 69 6e 63 6c 75 64 S..nf.\fB#includ
02b0: 65 20 3c 74 6b 2e 68 3e 5c 66 52 0a 2e 73 70 0a e <tk.h>\fR..sp.
02c0: 54 6b 5f 50 68 6f 74 6f 48 61 6e 64 6c 65 0a 5c Tk_PhotoHandle.\
02d0: 66 42 54 6b 5f 46 69 6e 64 50 68 6f 74 6f 5c 66 fBTk_FindPhoto\f
02e0: 52 28 5c 66 49 69 6e 74 65 72 70 2c 20 69 6d 61 R(\fIinterp, ima
02f0: 67 65 4e 61 6d 65 5c 66 52 29 0a 2e 73 70 0a 69 geName\fR)..sp.i
0300: 6e 74 0a 5c 66 42 54 6b 5f 50 68 6f 74 6f 50 75 nt.\fBTk_PhotoPu
0310: 74 42 6c 6f 63 6b 5c 66 52 28 5c 66 49 69 6e 74 tBlock\fR(\fIint
0320: 65 72 70 2c 20 68 61 6e 64 6c 65 2c 20 62 6c 6f erp, handle, blo
0330: 63 6b 50 74 72 2c 20 78 2c 20 79 2c 20 77 69 64 ckPtr, x, y, wid
0340: 74 68 2c 20 68 65 69 67 68 74 2c 5c 0a 63 6f 6d th, height,\.com
0350: 70 52 75 6c 65 5c 66 52 29 0a 2e 73 70 0a 69 6e pRule\fR)..sp.in
0360: 74 0a 5c 66 42 54 6b 5f 50 68 6f 74 6f 50 75 74 t.\fBTk_PhotoPut
0370: 5a 6f 6f 6d 65 64 42 6c 6f 63 6b 5c 66 52 28 5c ZoomedBlock\fR(\
0380: 66 49 69 6e 74 65 72 70 2c 20 68 61 6e 64 6c 65 fIinterp, handle
0390: 2c 20 62 6c 6f 63 6b 50 74 72 2c 20 78 2c 20 79 , blockPtr, x, y
03a0: 2c 20 77 69 64 74 68 2c 20 68 65 69 67 68 74 2c , width, height,
03b0: 5c 0a 7a 6f 6f 6d 58 2c 20 7a 6f 6f 6d 59 2c 20 \.zoomX, zoomY,
03c0: 73 75 62 73 61 6d 70 6c 65 58 2c 20 73 75 62 73 subsampleX, subs
03d0: 61 6d 70 6c 65 59 2c 20 63 6f 6d 70 52 75 6c 65 ampleY, compRule
03e0: 5c 66 52 29 0a 2e 73 70 0a 69 6e 74 0a 5c 66 42 \fR)..sp.int.\fB
03f0: 54 6b 5f 50 68 6f 74 6f 47 65 74 49 6d 61 67 65 Tk_PhotoGetImage
0400: 5c 66 52 28 5c 66 49 68 61 6e 64 6c 65 2c 20 62 \fR(\fIhandle, b
0410: 6c 6f 63 6b 50 74 72 5c 66 52 29 0a 2e 73 70 0a lockPtr\fR)..sp.
0420: 76 6f 69 64 0a 5c 66 42 54 6b 5f 50 68 6f 74 6f void.\fBTk_Photo
0430: 42 6c 61 6e 6b 5c 66 52 28 5c 66 49 68 61 6e 64 Blank\fR(\fIhand
0440: 6c 65 5c 66 52 29 0a 2e 73 70 0a 69 6e 74 0a 5c le\fR)..sp.int.\
0450: 66 42 54 6b 5f 50 68 6f 74 6f 45 78 70 61 6e 64 fBTk_PhotoExpand
0460: 5c 66 52 28 5c 66 49 69 6e 74 65 72 70 2c 20 68 \fR(\fIinterp, h
0470: 61 6e 64 6c 65 2c 20 77 69 64 74 68 2c 20 68 65 andle, width, he
0480: 69 67 68 74 5c 66 52 29 0a 2e 73 70 0a 76 6f 69 ight\fR)..sp.voi
0490: 64 0a 5c 66 42 54 6b 5f 50 68 6f 74 6f 47 65 74 d.\fBTk_PhotoGet
04a0: 53 69 7a 65 5c 66 52 28 5c 66 49 68 61 6e 64 6c Size\fR(\fIhandl
04b0: 65 2c 20 77 69 64 74 68 50 74 72 2c 20 68 65 69 e, widthPtr, hei
04c0: 67 68 74 50 74 72 5c 66 52 29 0a 2e 73 70 0a 69 ghtPtr\fR)..sp.i
04d0: 6e 74 0a 5c 66 42 54 6b 5f 50 68 6f 74 6f 53 65 nt.\fBTk_PhotoSe
04e0: 74 53 69 7a 65 5c 66 52 28 5c 66 49 69 6e 74 65 tSize\fR(\fIinte
04f0: 72 70 2e 20 68 61 6e 64 6c 65 2c 20 77 69 64 74 rp. handle, widt
0500: 68 2c 20 68 65 69 67 68 74 5c 66 52 29 0a 2e 53 h, height\fR)..S
0510: 48 20 41 52 47 55 4d 45 4e 54 53 0a 2e 41 53 20 H ARGUMENTS..AS
0520: 54 6b 5f 50 68 6f 74 6f 49 6d 61 67 65 42 6c 6f Tk_PhotoImageBlo
0530: 63 6b 20 77 69 6e 64 6f 77 5f 70 61 74 68 0a 2e ck window_path..
0540: 41 50 20 54 63 6c 5f 49 6e 74 65 72 70 20 2a 69 AP Tcl_Interp *i
0550: 6e 74 65 72 70 20 69 6e 0a 49 6e 74 65 72 70 72 nterp in.Interpr
0560: 65 74 65 72 20 69 6e 20 77 68 69 63 68 20 69 6d eter in which im
0570: 61 67 65 20 77 61 73 20 63 72 65 61 74 65 64 20 age was created
0580: 61 6e 64 20 69 6e 20 77 68 69 63 68 20 65 72 72 and in which err
0590: 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 69 73 0a or reporting is.
05a0: 74 6f 20 62 65 20 64 6f 6e 65 2e 0a 2e 41 50 20 to be done...AP
05b0: 22 63 6f 6e 73 74 20 63 68 61 72 22 20 2a 69 6d "const char" *im
05c0: 61 67 65 4e 61 6d 65 20 69 6e 0a 4e 61 6d 65 20 ageName in.Name
05d0: 6f 66 20 74 68 65 20 70 68 6f 74 6f 20 69 6d 61 of the photo ima
05e0: 67 65 2e 0a 2e 41 50 20 54 6b 5f 50 68 6f 74 6f ge...AP Tk_Photo
05f0: 48 61 6e 64 6c 65 20 68 61 6e 64 6c 65 20 69 6e Handle handle in
0600: 0a 4f 70 61 71 75 65 20 68 61 6e 64 6c 65 20 69 .Opaque handle i
0610: 64 65 6e 74 69 66 79 69 6e 67 20 74 68 65 20 70 dentifying the p
0620: 68 6f 74 6f 20 69 6d 61 67 65 20 74 6f 20 62 65 hoto image to be
0630: 20 61 66 66 65 63 74 65 64 2e 0a 2e 41 50 20 54 affected...AP T
0640: 6b 5f 50 68 6f 74 6f 49 6d 61 67 65 42 6c 6f 63 k_PhotoImageBloc
0650: 6b 20 2a 62 6c 6f 63 6b 50 74 72 20 69 6e 0a 53 k *blockPtr in.S
0660: 70 65 63 69 66 69 65 73 20 74 68 65 20 61 64 64 pecifies the add
0670: 72 65 73 73 20 61 6e 64 20 73 74 6f 72 61 67 65 ress and storage
0680: 20 6c 61 79 6f 75 74 20 6f 66 20 69 6d 61 67 65 layout of image
0690: 20 64 61 74 61 2e 0a 2e 41 50 20 69 6e 74 20 78 data...AP int x
06a0: 20 69 6e 0a 53 70 65 63 69 66 69 65 73 20 74 68 in.Specifies th
06b0: 65 20 58 20 63 6f 6f 72 64 69 6e 61 74 65 20 77 e X coordinate w
06c0: 68 65 72 65 20 74 68 65 20 74 6f 70 2d 6c 65 66 here the top-lef
06d0: 74 20 63 6f 72 6e 65 72 20 6f 66 20 74 68 65 20 t corner of the
06e0: 62 6c 6f 63 6b 20 69 73 0a 74 6f 20 62 65 20 70 block is.to be p
06f0: 6c 61 63 65 64 20 77 69 74 68 69 6e 20 74 68 65 laced within the
0700: 20 69 6d 61 67 65 2e 0a 2e 41 50 20 69 6e 74 20 image...AP int
0710: 79 20 69 6e 0a 53 70 65 63 69 66 69 65 73 20 74 y in.Specifies t
0720: 68 65 20 59 20 63 6f 6f 72 64 69 6e 61 74 65 20 he Y coordinate
0730: 77 68 65 72 65 20 74 68 65 20 74 6f 70 2d 6c 65 where the top-le
0740: 66 74 20 63 6f 72 6e 65 72 20 6f 66 20 74 68 65 ft corner of the
0750: 20 62 6c 6f 63 6b 20 69 73 0a 74 6f 20 62 65 20 block is.to be
0760: 70 6c 61 63 65 64 20 77 69 74 68 69 6e 20 74 68 placed within th
0770: 65 20 69 6d 61 67 65 2e 0a 2e 41 50 20 69 6e 74 e image...AP int
0780: 20 77 69 64 74 68 20 69 6e 0a 53 70 65 63 69 66 width in.Specif
0790: 69 65 73 20 74 68 65 20 77 69 64 74 68 20 6f 66 ies the width of
07a0: 20 74 68 65 20 69 6d 61 67 65 20 61 72 65 61 20 the image area
07b0: 74 6f 20 62 65 20 61 66 66 65 63 74 65 64 20 28 to be affected (
07c0: 66 6f 72 0a 5c 66 42 54 6b 5f 50 68 6f 74 6f 50 for.\fBTk_PhotoP
07d0: 75 74 42 6c 6f 63 6b 5c 66 52 29 20 6f 72 20 74 utBlock\fR) or t
07e0: 68 65 20 64 65 73 69 72 65 64 20 69 6d 61 67 65 he desired image
07f0: 20 77 69 64 74 68 20 28 66 6f 72 0a 5c 66 42 54 width (for.\fBT
0800: 6b 5f 50 68 6f 74 6f 45 78 70 61 6e 64 5c 66 52 k_PhotoExpand\fR
0810: 20 61 6e 64 20 5c 66 42 54 6b 5f 50 68 6f 74 6f and \fBTk_Photo
0820: 53 65 74 53 69 7a 65 5c 66 52 29 2e 0a 2e 41 50 SetSize\fR)...AP
0830: 20 69 6e 74 20 63 6f 6d 70 52 75 6c 65 20 69 6e int compRule in
0840: 0a 53 70 65 63 69 66 69 65 73 20 74 68 65 20 63 .Specifies the c
0850: 6f 6d 70 6f 73 69 74 69 6e 67 20 72 75 6c 65 20 ompositing rule
0860: 75 73 65 64 20 77 68 65 6e 20 63 6f 6d 62 69 6e used when combin
0870: 69 6e 67 20 74 72 61 6e 73 70 61 72 65 6e 74 20 ing transparent
0880: 70 69 78 65 6c 73 0a 69 6e 20 61 20 62 6c 6f 63 pixels.in a bloc
0890: 6b 20 6f 66 20 64 61 74 61 20 77 69 74 68 20 61 k of data with a
08a0: 20 70 68 6f 74 6f 20 69 6d 61 67 65 2e 20 20 4d photo image. M
08b0: 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 5c 66 ust be one of.\f
08c0: 42 54 4b 5f 50 48 4f 54 4f 5f 43 4f 4d 50 4f 53 BTK_PHOTO_COMPOS
08d0: 49 54 45 5f 4f 56 45 52 4c 41 59 5c 66 52 20 28 ITE_OVERLAY\fR (
08e0: 77 68 69 63 68 20 70 75 74 73 20 74 68 65 20 62 which puts the b
08f0: 6c 6f 63 6b 20 6f 66 20 64 61 74 61 20 6f 76 65 lock of data ove
0900: 72 20 74 68 65 20 74 6f 70 0a 6f 66 20 74 68 65 r the top.of the
0910: 20 65 78 69 73 74 69 6e 67 20 70 68 6f 74 6f 20 existing photo
0920: 69 6d 61 67 65 2c 20 77 69 74 68 20 74 68 65 20 image, with the
0930: 70 72 65 76 69 6f 75 73 20 63 6f 6e 74 65 6e 74 previous content
0940: 73 20 73 68 6f 77 69 6e 67 0a 74 68 72 6f 75 67 s showing.throug
0950: 68 20 69 6e 20 74 68 65 20 74 72 61 6e 73 70 61 h in the transpa
0960: 72 65 6e 74 20 62 69 74 73 29 20 6f 72 20 5c 66 rent bits) or \f
0970: 42 54 4b 5f 50 48 4f 54 4f 5f 43 4f 4d 50 4f 53 BTK_PHOTO_COMPOS
0980: 49 54 45 5f 53 45 54 5c 66 52 20 28 77 68 69 63 ITE_SET\fR (whic
0990: 68 0a 64 69 73 63 61 72 64 73 20 74 68 65 20 65 h.discards the e
09a0: 78 69 73 74 69 6e 67 20 70 68 6f 74 6f 20 69 6d xisting photo im
09b0: 61 67 65 20 63 6f 6e 74 65 6e 74 73 20 69 6e 20 age contents in
09c0: 74 68 65 20 72 65 63 74 61 6e 67 6c 65 20 63 6f the rectangle co
09d0: 76 65 72 65 64 20 62 79 0a 74 68 65 20 64 61 74 vered by.the dat
09e0: 61 20 62 6c 6f 63 6b 2e 29 0a 2e 41 50 20 69 6e a block.)..AP in
09f0: 74 20 68 65 69 67 68 74 20 69 6e 0a 53 70 65 63 t height in.Spec
0a00: 69 66 69 65 73 20 74 68 65 20 68 65 69 67 68 74 ifies the height
0a10: 20 6f 66 20 74 68 65 20 69 6d 61 67 65 20 61 72 of the image ar
0a20: 65 61 20 74 6f 20 62 65 20 61 66 66 65 63 74 65 ea to be affecte
0a30: 64 20 28 66 6f 72 0a 5c 66 42 54 6b 5f 50 68 6f d (for.\fBTk_Pho
0a40: 74 6f 50 75 74 42 6c 6f 63 6b 5c 66 52 29 20 6f toPutBlock\fR) o
0a50: 72 20 74 68 65 20 64 65 73 69 72 65 64 20 69 6d r the desired im
0a60: 61 67 65 20 68 65 69 67 68 74 20 28 66 6f 72 0a age height (for.
0a70: 5c 66 42 54 6b 5f 50 68 6f 74 6f 45 78 70 61 6e \fBTk_PhotoExpan
0a80: 64 5c 66 52 20 61 6e 64 20 5c 66 42 54 6b 5f 50 d\fR and \fBTk_P
0a90: 68 6f 74 6f 53 65 74 53 69 7a 65 5c 66 52 29 2e hotoSetSize\fR).
0aa0: 0a 2e 41 50 20 69 6e 74 20 2a 77 69 64 74 68 50 ..AP int *widthP
0ab0: 74 72 20 6f 75 74 0a 50 6f 69 6e 74 65 72 20 74 tr out.Pointer t
0ac0: 6f 20 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 77 68 o location in wh
0ad0: 69 63 68 20 74 6f 20 73 74 6f 72 65 20 74 68 65 ich to store the
0ae0: 20 69 6d 61 67 65 20 77 69 64 74 68 2e 0a 2e 41 image width...A
0af0: 50 20 69 6e 74 20 2a 68 65 69 67 68 74 50 74 72 P int *heightPtr
0b00: 20 6f 75 74 0a 50 6f 69 6e 74 65 72 20 74 6f 20 out.Pointer to
0b10: 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 77 68 69 63 location in whic
0b20: 68 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 69 h to store the i
0b30: 6d 61 67 65 20 68 65 69 67 68 74 2e 0a 2e 41 50 mage height...AP
0b40: 20 69 6e 74 20 73 75 62 73 61 6d 70 6c 65 58 20 int subsampleX
0b50: 69 6e 0a 53 70 65 63 69 66 69 65 73 20 74 68 65 in.Specifies the
0b60: 20 73 75 62 73 61 6d 70 6c 69 6e 67 20 66 61 63 subsampling fac
0b70: 74 6f 72 20 69 6e 20 74 68 65 20 58 20 64 69 72 tor in the X dir
0b80: 65 63 74 69 6f 6e 20 66 6f 72 20 69 6e 70 75 74 ection for input
0b90: 0a 69 6d 61 67 65 20 64 61 74 61 2e 0a 2e 41 50 .image data...AP
0ba0: 20 69 6e 74 20 73 75 62 73 61 6d 70 6c 65 59 20 int subsampleY
0bb0: 69 6e 0a 53 70 65 63 69 66 69 65 73 20 74 68 65 in.Specifies the
0bc0: 20 73 75 62 73 61 6d 70 6c 69 6e 67 20 66 61 63 subsampling fac
0bd0: 74 6f 72 20 69 6e 20 74 68 65 20 59 20 64 69 72 tor in the Y dir
0be0: 65 63 74 69 6f 6e 20 66 6f 72 20 69 6e 70 75 74 ection for input
0bf0: 0a 69 6d 61 67 65 20 64 61 74 61 2e 0a 2e 41 50 .image data...AP
0c00: 20 69 6e 74 20 7a 6f 6f 6d 58 20 69 6e 0a 53 70 int zoomX in.Sp
0c10: 65 63 69 66 69 65 73 20 74 68 65 20 7a 6f 6f 6d ecifies the zoom
0c20: 20 66 61 63 74 6f 72 20 74 6f 20 62 65 20 61 70 factor to be ap
0c30: 70 6c 69 65 64 20 69 6e 20 74 68 65 20 58 20 64 plied in the X d
0c40: 69 72 65 63 74 69 6f 6e 20 74 6f 20 70 69 78 65 irection to pixe
0c50: 6c 73 0a 62 65 69 6e 67 20 77 72 69 74 74 65 6e ls.being written
0c60: 20 74 6f 20 74 68 65 20 70 68 6f 74 6f 20 69 6d to the photo im
0c70: 61 67 65 2e 0a 2e 41 50 20 69 6e 74 20 7a 6f 6f age...AP int zoo
0c80: 6d 59 20 69 6e 0a 53 70 65 63 69 66 69 65 73 20 mY in.Specifies
0c90: 74 68 65 20 7a 6f 6f 6d 20 66 61 63 74 6f 72 20 the zoom factor
0ca0: 74 6f 20 62 65 20 61 70 70 6c 69 65 64 20 69 6e to be applied in
0cb0: 20 74 68 65 20 59 20 64 69 72 65 63 74 69 6f 6e the Y direction
0cc0: 20 74 6f 20 70 69 78 65 6c 73 0a 62 65 69 6e 67 to pixels.being
0cd0: 20 77 72 69 74 74 65 6e 20 74 6f 20 74 68 65 20 written to the
0ce0: 70 68 6f 74 6f 20 69 6d 61 67 65 2e 0a 2e 42 45 photo image...BE
0cf0: 0a 2e 53 48 20 44 45 53 43 52 49 50 54 49 4f 4e ..SH DESCRIPTION
0d00: 0a 2e 50 50 0a 5c 66 42 54 6b 5f 46 69 6e 64 50 ..PP.\fBTk_FindP
0d10: 68 6f 74 6f 5c 66 52 20 72 65 74 75 72 6e 73 20 hoto\fR returns
0d20: 61 6e 20 6f 70 61 71 75 65 20 68 61 6e 64 6c 65 an opaque handle
0d30: 20 74 68 61 74 20 69 73 20 75 73 65 64 20 74 6f that is used to
0d40: 20 69 64 65 6e 74 69 66 79 20 61 0a 70 61 72 74 identify a.part
0d50: 69 63 75 6c 61 72 20 70 68 6f 74 6f 20 69 6d 61 icular photo ima
0d60: 67 65 20 74 6f 20 74 68 65 20 6f 74 68 65 72 20 ge to the other
0d70: 70 72 6f 63 65 64 75 72 65 73 2e 20 20 54 68 65 procedures. The
0d80: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
0d90: 65 0a 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6d e.name of the im
0da0: 61 67 65 2c 20 74 68 61 74 20 69 73 2c 20 74 68 age, that is, th
0db0: 65 20 6e 61 6d 65 20 73 70 65 63 69 66 69 65 64 e name specified
0dc0: 20 74 6f 20 74 68 65 20 5c 66 42 69 6d 61 67 65 to the \fBimage
0dd0: 20 63 72 65 61 74 65 0a 70 68 6f 74 6f 5c 66 52 create.photo\fR
0de0: 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 61 73 73 command, or ass
0df0: 69 67 6e 65 64 20 62 79 20 74 68 61 74 20 63 6f igned by that co
0e00: 6d 6d 61 6e 64 20 69 66 20 6e 6f 20 6e 61 6d 65 mmand if no name
0e10: 20 77 61 73 20 73 70 65 63 69 66 69 65 64 2e 0a was specified..
0e20: 49 66 20 5c 66 49 69 6d 61 67 65 4e 61 6d 65 5c If \fIimageName\
0e30: 66 52 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 fR does not exis
0e40: 74 20 6f 72 20 69 73 20 6e 6f 74 20 61 20 70 68 t or is not a ph
0e50: 6f 74 6f 20 69 6d 61 67 65 2c 0a 5c 66 42 54 6b oto image,.\fBTk
0e60: 5f 46 69 6e 64 50 68 6f 74 6f 5c 66 52 20 72 65 _FindPhoto\fR re
0e70: 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2e 50 50 0a turns NULL...PP.
0e80: 5c 66 42 54 6b 5f 50 68 6f 74 6f 50 75 74 42 6c \fBTk_PhotoPutBl
0e90: 6f 63 6b 5c 66 52 20 69 73 20 75 73 65 64 20 74 ock\fR is used t
0ea0: 6f 20 73 75 70 70 6c 79 20 62 6c 6f 63 6b 73 20 o supply blocks
0eb0: 6f 66 20 69 6d 61 67 65 20 64 61 74 61 20 74 6f of image data to
0ec0: 20 62 65 0a 64 69 73 70 6c 61 79 65 64 2e 20 20 be.displayed.
0ed0: 54 68 65 20 63 61 6c 6c 20 61 66 66 65 63 74 73 The call affects
0ee0: 20 61 6e 20 61 72 65 61 20 6f 66 20 74 68 65 20 an area of the
0ef0: 69 6d 61 67 65 20 6f 66 20 73 69 7a 65 0a 5c 66 image of size.\f
0f00: 49 77 69 64 74 68 5c 66 52 20 78 20 5c 66 49 68 Iwidth\fR x \fIh
0f10: 65 69 67 68 74 5c 66 52 20 70 69 78 65 6c 73 2c eight\fR pixels,
0f20: 20 77 69 74 68 20 69 74 73 20 74 6f 70 2d 6c 65 with its top-le
0f30: 66 74 20 63 6f 72 6e 65 72 20 61 74 0a 63 6f 6f ft corner at.coo
0f40: 72 64 69 6e 61 74 65 73 20 28 5c 66 49 78 5c 66 rdinates (\fIx\f
0f50: 52 2c 5c 66 49 79 5c 66 52 29 2e 20 20 41 6c 6c R,\fIy\fR). All
0f60: 20 6f 66 20 5c 66 49 77 69 64 74 68 5c 66 52 2c of \fIwidth\fR,
0f70: 20 5c 66 49 68 65 69 67 68 74 5c 66 52 2c 0a 5c \fIheight\fR,.\
0f80: 66 49 78 5c 66 52 2c 20 61 6e 64 20 5c 66 49 79 fIx\fR, and \fIy
0f90: 5c 66 52 20 6d 75 73 74 20 62 65 20 6e 6f 6e 2d \fR must be non-
0fa0: 6e 65 67 61 74 69 76 65 2e 0a 49 66 20 70 61 72 negative..If par
0fb0: 74 20 6f 66 20 74 68 69 73 20 61 72 65 61 20 6c t of this area l
0fc0: 69 65 73 20 6f 75 74 73 69 64 65 20 74 68 65 0a ies outside the.
0fd0: 63 75 72 72 65 6e 74 20 62 6f 75 6e 64 73 20 6f current bounds o
0fe0: 66 20 74 68 65 20 69 6d 61 67 65 2c 20 74 68 65 f the image, the
0ff0: 20 69 6d 61 67 65 20 77 69 6c 6c 20 62 65 20 65 image will be e
1000: 78 70 61 6e 64 65 64 20 74 6f 20 69 6e 63 6c 75 xpanded to inclu
1010: 64 65 20 74 68 65 0a 61 72 65 61 2c 20 75 6e 6c de the.area, unl
1020: 65 73 73 20 74 68 65 20 75 73 65 72 20 68 61 73 ess the user has
1030: 20 73 70 65 63 69 66 69 65 64 20 61 6e 20 65 78 specified an ex
1040: 70 6c 69 63 69 74 20 69 6d 61 67 65 20 73 69 7a plicit image siz
1050: 65 20 77 69 74 68 20 74 68 65 0a 5c 66 42 5c 2d e with the.\fB\-
1060: 77 69 64 74 68 5c 66 52 20 61 6e 64 2f 6f 72 20 width\fR and/or
1070: 5c 66 42 5c 2d 68 65 69 67 68 74 5c 66 52 20 77 \fB\-height\fR w
1080: 69 64 67 65 74 20 63 6f 6e 66 69 67 75 72 61 74 idget configurat
1090: 69 6f 6e 20 6f 70 74 69 6f 6e 73 0a 28 73 65 65 ion options.(see
10a0: 20 70 68 6f 74 6f 28 6e 29 29 3b 20 69 6e 20 74 photo(n)); in t
10b0: 68 61 74 0a 63 61 73 65 20 74 68 65 20 61 72 65 hat.case the are
10c0: 61 20 69 73 20 73 69 6c 65 6e 74 6c 79 20 63 6c a is silently cl
10d0: 69 70 70 65 64 20 74 6f 20 74 68 65 20 69 6d 61 ipped to the ima
10e0: 67 65 20 62 6f 75 6e 64 61 72 69 65 73 2e 0a 2e ge boundaries...
10f0: 50 50 0a 54 68 65 20 5c 66 49 62 6c 6f 63 6b 5c PP.The \fIblock\
1100: 66 52 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 fR parameter is
1110: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 5c a pointer to a.\
1120: 66 42 54 6b 5f 50 68 6f 74 6f 49 6d 61 67 65 42 fBTk_PhotoImageB
1130: 6c 6f 63 6b 5c 66 52 20 73 74 72 75 63 74 75 72 lock\fR structur
1140: 65 2c 20 64 65 66 69 6e 65 64 20 61 73 20 66 6f e, defined as fo
1150: 6c 6c 6f 77 73 3a 0a 2e 43 53 0a 74 79 70 65 64 llows:..CS.typed
1160: 65 66 20 73 74 72 75 63 74 20 7b 0a 20 20 20 20 ef struct {.
1170: 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 5c unsigned char *\
1180: 66 49 70 69 78 65 6c 50 74 72 5c 66 52 3b 0a 20 fIpixelPtr\fR;.
1190: 20 20 20 69 6e 74 20 5c 66 49 77 69 64 74 68 5c int \fIwidth\
11a0: 66 52 3b 0a 20 20 20 20 69 6e 74 20 5c 66 49 68 fR;. int \fIh
11b0: 65 69 67 68 74 5c 66 52 3b 0a 20 20 20 20 69 6e eight\fR;. in
11c0: 74 20 5c 66 49 70 69 74 63 68 5c 66 52 3b 0a 20 t \fIpitch\fR;.
11d0: 20 20 20 69 6e 74 20 5c 66 49 70 69 78 65 6c 53 int \fIpixelS
11e0: 69 7a 65 5c 66 52 3b 0a 20 20 20 20 69 6e 74 20 ize\fR;. int
11f0: 5c 66 49 6f 66 66 73 65 74 5c 66 52 5b 34 5d 3b \fIoffset\fR[4];
1200: 0a 7d 20 5c 66 42 54 6b 5f 50 68 6f 74 6f 49 6d .} \fBTk_PhotoIm
1210: 61 67 65 42 6c 6f 63 6b 5c 66 52 3b 0a 2e 43 45 ageBlock\fR;..CE
1220: 0a 54 68 65 20 5c 66 49 70 69 78 65 6c 50 74 72 .The \fIpixelPtr
1230: 5c 66 52 20 66 69 65 6c 64 20 70 6f 69 6e 74 73 \fR field points
1240: 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 69 to the first pi
1250: 78 65 6c 2c 20 74 68 61 74 20 69 73 2c 20 74 68 xel, that is, th
1260: 65 0a 74 6f 70 2d 6c 65 66 74 20 70 69 78 65 6c e.top-left pixel
1270: 20 69 6e 20 74 68 65 20 62 6c 6f 63 6b 2e 0a 54 in the block..T
1280: 68 65 20 5c 66 49 77 69 64 74 68 5c 66 52 20 61 he \fIwidth\fR a
1290: 6e 64 20 5c 66 49 68 65 69 67 68 74 5c 66 52 20 nd \fIheight\fR
12a0: 66 69 65 6c 64 73 20 73 70 65 63 69 66 79 20 74 fields specify t
12b0: 68 65 20 64 69 6d 65 6e 73 69 6f 6e 73 20 6f 66 he dimensions of
12c0: 20 74 68 65 0a 62 6c 6f 63 6b 20 6f 66 20 70 69 the.block of pi
12d0: 78 65 6c 73 2e 20 20 54 68 65 20 5c 66 49 70 69 xels. The \fIpi
12e0: 78 65 6c 53 69 7a 65 5c 66 52 20 66 69 65 6c 64 xelSize\fR field
12f0: 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 61 specifies the a
1300: 64 64 72 65 73 73 0a 64 69 66 66 65 72 65 6e 63 ddress.differenc
1310: 65 20 62 65 74 77 65 65 6e 20 74 77 6f 20 68 6f e between two ho
1320: 72 69 7a 6f 6e 74 61 6c 6c 79 20 61 64 6a 61 63 rizontally adjac
1330: 65 6e 74 20 70 69 78 65 6c 73 2e 20 20 49 74 20 ent pixels. It
1340: 73 68 6f 75 6c 64 20 62 65 20 34 20 66 6f 72 0a should be 4 for.
1350: 52 47 42 20 61 6e 64 20 32 20 66 6f 72 20 67 72 RGB and 2 for gr
1360: 61 79 73 63 61 6c 65 20 69 6d 61 67 65 20 64 61 ayscale image da
1370: 74 61 2e 20 20 4f 74 68 65 72 20 76 61 6c 75 65 ta. Other value
1380: 73 20 61 72 65 20 70 6f 73 73 69 62 6c 65 2c 20 s are possible,
1390: 69 66 20 74 68 65 0a 6f 66 66 73 65 74 73 20 69 if the.offsets i
13a0: 6e 20 74 68 65 20 5c 66 49 6f 66 66 73 65 74 5c n the \fIoffset\
13b0: 66 52 20 61 72 72 61 79 20 61 72 65 20 61 64 6a fR array are adj
13c0: 75 73 74 65 64 20 61 63 63 6f 72 64 69 6e 67 6c usted accordingl
13d0: 79 20 28 65 2e 67 2e 20 66 6f 72 0a 72 65 64 2c y (e.g. for.red,
13e0: 20 67 72 65 65 6e 20 61 6e 64 20 62 6c 75 65 20 green and blue
13f0: 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 64 data stored in d
1400: 69 66 66 65 72 65 6e 74 20 70 6c 61 6e 65 73 29 ifferent planes)
1410: 2e 20 20 55 73 69 6e 67 20 73 75 63 68 20 61 0a . Using such a.
1420: 6c 61 79 6f 75 74 20 69 73 20 73 74 72 6f 6e 67 layout is strong
1430: 6c 79 20 64 69 73 63 6f 75 72 61 67 65 64 2c 20 ly discouraged,
1440: 74 68 6f 75 67 68 2e 20 44 75 65 20 74 6f 20 61 though. Due to a
1450: 20 62 75 67 2c 20 69 74 20 6d 69 67 68 74 20 6e bug, it might n
1460: 6f 74 20 77 6f 72 6b 0a 63 6f 72 72 65 63 74 6c ot work.correctl
1470: 79 20 69 66 20 61 6e 20 61 6c 70 68 61 20 63 68 y if an alpha ch
1480: 61 6e 6e 65 6c 20 69 73 20 70 72 6f 76 69 64 65 annel is provide
1490: 64 2e 20 28 73 65 65 20 74 68 65 20 5c 66 42 42 d. (see the \fBB
14a0: 55 47 53 5c 66 52 20 73 65 63 74 69 6f 6e 0a 62 UGS\fR section.b
14b0: 65 6c 6f 77 29 2e 20 54 68 65 20 5c 66 49 70 69 elow). The \fIpi
14c0: 74 63 68 5c 66 52 20 66 69 65 6c 64 20 73 70 65 tch\fR field spe
14d0: 63 69 66 69 65 73 20 74 68 65 0a 61 64 64 72 65 cifies the.addre
14e0: 73 73 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 ss difference be
14f0: 74 77 65 65 6e 20 74 77 6f 20 76 65 72 74 69 63 tween two vertic
1500: 61 6c 6c 79 20 61 64 6a 61 63 65 6e 74 20 70 69 ally adjacent pi
1510: 78 65 6c 73 2e 20 20 54 68 65 0a 5c 66 49 6f 66 xels. The.\fIof
1520: 66 73 65 74 5c 66 52 20 61 72 72 61 79 20 63 6f fset\fR array co
1530: 6e 74 61 69 6e 73 20 74 68 65 20 6f 66 66 73 65 ntains the offse
1540: 74 73 20 66 72 6f 6d 20 74 68 65 20 61 64 64 72 ts from the addr
1550: 65 73 73 20 6f 66 20 61 20 70 69 78 65 6c 0a 74 ess of a pixel.t
1560: 6f 20 74 68 65 20 61 64 64 72 65 73 73 65 73 20 o the addresses
1570: 6f 66 20 74 68 65 20 62 79 74 65 73 20 63 6f 6e of the bytes con
1580: 74 61 69 6e 69 6e 67 20 74 68 65 20 72 65 64 2c taining the red,
1590: 20 67 72 65 65 6e 2c 20 62 6c 75 65 20 61 6e 64 green, blue and
15a0: 20 61 6c 70 68 61 0a 28 74 72 61 6e 73 70 61 72 alpha.(transpar
15b0: 65 6e 63 79 29 20 63 6f 6d 70 6f 6e 65 6e 74 73 ency) components
15c0: 2e 20 20 49 66 20 74 68 65 20 6f 66 66 73 65 74 . If the offset
15d0: 73 20 66 6f 72 20 72 65 64 2c 20 67 72 65 65 6e s for red, green
15e0: 20 61 6e 64 20 62 6c 75 65 20 61 72 65 0a 65 71 and blue are.eq
15f0: 75 61 6c 2c 20 74 68 65 20 69 6d 61 67 65 20 69 ual, the image i
1600: 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
1610: 20 67 72 61 79 73 63 61 6c 65 2e 20 49 66 20 74 grayscale. If t
1620: 68 65 79 20 64 69 66 66 65 72 2c 20 52 47 42 20 hey differ, RGB
1630: 64 61 74 61 0a 69 73 20 61 73 73 75 6d 65 64 2e data.is assumed.
1640: 20 4e 6f 72 6d 61 6c 6c 79 20 74 68 65 20 6f 66 Normally the of
1650: 66 73 65 74 73 20 77 69 6c 6c 20 62 65 20 30 2c fsets will be 0,
1660: 20 31 2c 20 32 2c 20 33 20 66 6f 72 20 52 47 42 1, 2, 3 for RGB
1670: 20 64 61 74 61 0a 61 6e 64 20 30 2c 20 30 2c 20 data.and 0, 0,
1680: 30 2c 20 31 20 66 6f 72 20 67 72 61 79 73 63 61 0, 1 for graysca
1690: 6c 65 2e 20 20 49 74 20 69 73 20 70 6f 73 73 69 le. It is possi
16a0: 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20 69 ble to provide i
16b0: 6d 61 67 65 20 64 61 74 61 0a 77 69 74 68 6f 75 mage data.withou
16c0: 74 20 61 6e 20 61 6c 70 68 61 20 63 68 61 6e 6e t an alpha chann
16d0: 65 6c 20 62 79 20 73 65 74 74 69 6e 67 20 74 68 el by setting th
16e0: 65 20 6f 66 66 73 65 74 20 66 6f 72 20 61 6c 70 e offset for alp
16f0: 68 61 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 ha to a negative
1700: 0a 76 61 6c 75 65 20 61 6e 64 20 61 64 6a 75 73 .value and adjus
1710: 74 69 6e 67 20 74 68 65 20 5c 66 49 70 69 78 65 ting the \fIpixe
1720: 6c 53 69 7a 65 5c 66 52 20 66 69 65 6c 64 20 61 lSize\fR field a
1730: 63 63 6f 72 64 69 6e 67 6c 79 2e 20 54 68 69 73 ccordingly. This
1740: 20 75 73 65 20 69 73 0a 64 69 73 63 6f 75 72 61 use is.discoura
1750: 67 65 64 2c 20 74 68 6f 75 67 68 20 28 73 65 65 ged, though (see
1760: 20 74 68 65 20 5c 66 42 42 55 47 53 5c 66 52 20 the \fBBUGS\fR
1770: 73 65 63 74 69 6f 6e 20 62 65 6c 6f 77 29 2e 0a section below)..
1780: 2e 50 50 0a 54 68 65 20 5c 66 49 63 6f 6d 70 52 .PP.The \fIcompR
1790: 75 6c 65 5c 66 52 20 70 61 72 61 6d 65 74 65 72 ule\fR parameter
17a0: 20 74 6f 20 5c 66 42 54 6b 5f 50 68 6f 74 6f 50 to \fBTk_PhotoP
17b0: 75 74 42 6c 6f 63 6b 5c 66 52 20 73 70 65 63 69 utBlock\fR speci
17c0: 66 69 65 73 20 61 0a 63 6f 6d 70 6f 73 69 74 69 fies a.compositi
17d0: 6e 67 20 72 75 6c 65 20 74 68 61 74 20 73 61 79 ng rule that say
17e0: 73 20 77 68 61 74 20 74 6f 20 64 6f 20 77 69 74 s what to do wit
17f0: 68 20 74 72 61 6e 73 70 61 72 65 6e 74 20 70 69 h transparent pi
1800: 78 65 6c 73 2e 20 20 54 68 65 0a 76 61 6c 75 65 xels. The.value
1810: 20 5c 66 42 54 4b 5f 50 48 4f 54 4f 5f 43 4f 4d \fBTK_PHOTO_COM
1820: 50 4f 53 49 54 45 5f 4f 56 45 52 4c 41 59 5c 66 POSITE_OVERLAY\f
1830: 52 20 73 61 79 73 20 74 68 61 74 20 74 68 65 20 R says that the
1840: 70 72 65 76 69 6f 75 73 20 63 6f 6e 74 65 6e 74 previous content
1850: 73 20 6f 66 0a 74 68 65 20 70 68 6f 74 6f 20 69 s of.the photo i
1860: 6d 61 67 65 20 73 68 6f 75 6c 64 20 73 68 6f 77 mage should show
1870: 20 74 68 72 6f 75 67 68 2c 20 61 6e 64 20 74 68 through, and th
1880: 65 20 76 61 6c 75 65 0a 5c 66 42 54 4b 5f 50 48 e value.\fBTK_PH
1890: 4f 54 4f 5f 43 4f 4d 50 4f 53 49 54 45 5f 53 45 OTO_COMPOSITE_SE
18a0: 54 5c 66 52 20 73 61 79 73 20 74 68 61 74 20 74 T\fR says that t
18b0: 68 65 20 70 72 65 76 69 6f 75 73 20 63 6f 6e 74 he previous cont
18c0: 65 6e 74 73 20 6f 66 20 74 68 65 20 70 68 6f 74 ents of the phot
18d0: 6f 0a 69 6d 61 67 65 20 73 68 6f 75 6c 64 20 62 o.image should b
18e0: 65 20 63 6f 6d 70 6c 65 74 65 6c 79 20 69 67 6e e completely ign
18f0: 6f 72 65 64 2c 20 61 6e 64 20 74 68 65 20 76 61 ored, and the va
1900: 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 62 6c lues from the bl
1910: 6f 63 6b 20 62 65 0a 63 6f 70 69 65 64 20 64 69 ock be.copied di
1920: 72 65 63 74 6c 79 20 61 63 72 6f 73 73 2e 20 20 rectly across.
1930: 54 68 65 20 62 65 68 61 76 69 6f 72 20 69 6e 20 The behavior in
1940: 54 6b 38 2e 33 20 61 6e 64 20 65 61 72 6c 69 65 Tk8.3 and earlie
1950: 72 20 77 61 73 0a 65 71 75 69 76 61 6c 65 6e 74 r was.equivalent
1960: 20 74 6f 20 68 61 76 69 6e 67 20 5c 66 42 54 4b to having \fBTK
1970: 5f 50 48 4f 54 4f 5f 43 4f 4d 50 4f 53 49 54 45 _PHOTO_COMPOSITE
1980: 5f 4f 56 45 52 4c 41 59 5c 66 52 20 61 73 20 61 _OVERLAY\fR as a
1990: 20 63 6f 6d 70 6f 73 69 74 69 6e 67 20 72 75 6c compositing rul
19a0: 65 2e 0a 2e 50 50 0a 54 68 65 20 76 61 6c 75 65 e...PP.The value
19b0: 20 67 69 76 65 6e 20 66 6f 72 20 74 68 65 20 5c given for the \
19c0: 66 49 77 69 64 74 68 5c 66 52 20 61 6e 64 20 5c fIwidth\fR and \
19d0: 66 49 68 65 69 67 68 74 5c 66 52 20 70 61 72 61 fIheight\fR para
19e0: 6d 65 74 65 72 73 20 74 6f 0a 5c 66 42 54 6b 5f meters to.\fBTk_
19f0: 50 68 6f 74 6f 50 75 74 42 6c 6f 63 6b 5c 66 52 PhotoPutBlock\fR
1a00: 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 74 6f 20 do not have to
1a10: 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 correspond to th
1a20: 65 20 76 61 6c 75 65 73 20 73 70 65 63 69 66 69 e values specifi
1a30: 65 64 0a 69 6e 20 5c 66 49 62 6c 6f 63 6b 5c 66 ed.in \fIblock\f
1a40: 52 2e 20 20 49 66 20 74 68 65 79 20 61 72 65 20 R. If they are
1a50: 73 6d 61 6c 6c 65 72 2c 20 5c 66 42 54 6b 5f 50 smaller, \fBTk_P
1a60: 68 6f 74 6f 50 75 74 42 6c 6f 63 6b 5c 66 52 20 hotoPutBlock\fR
1a70: 65 78 74 72 61 63 74 73 20 61 0a 73 75 62 2d 62 extracts a.sub-b
1a80: 6c 6f 63 6b 20 66 72 6f 6d 20 74 68 65 20 69 6d lock from the im
1a90: 61 67 65 20 64 61 74 61 20 73 75 70 70 6c 69 65 age data supplie
1aa0: 64 2e 20 20 49 66 20 74 68 65 79 20 61 72 65 20 d. If they are
1ab0: 6c 61 72 67 65 72 2c 20 74 68 65 20 64 61 74 61 larger, the data
1ac0: 0a 67 69 76 65 6e 20 61 72 65 20 72 65 70 6c 69 .given are repli
1ad0: 63 61 74 65 64 20 28 69 6e 20 61 20 74 69 6c 65 cated (in a tile
1ae0: 64 20 66 61 73 68 69 6f 6e 29 20 74 6f 20 66 69 d fashion) to fi
1af0: 6c 6c 20 74 68 65 20 73 70 65 63 69 66 69 65 64 ll the specified
1b00: 20 61 72 65 61 2e 0a 54 68 65 73 65 20 72 75 6c area..These rul
1b10: 65 73 20 6f 70 65 72 61 74 65 20 69 6e 64 65 70 es operate indep
1b20: 65 6e 64 65 6e 74 6c 79 20 69 6e 20 74 68 65 20 endently in the
1b30: 68 6f 72 69 7a 6f 6e 74 61 6c 20 61 6e 64 20 76 horizontal and v
1b40: 65 72 74 69 63 61 6c 0a 64 69 72 65 63 74 69 6f ertical.directio
1b50: 6e 73 2e 0a 2e 50 50 0a 5c 66 42 54 6b 5f 50 68 ns...PP.\fBTk_Ph
1b60: 6f 74 6f 50 75 74 42 6c 6f 63 6b 5c 66 52 20 6e otoPutBlock\fR n
1b70: 6f 72 6d 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 ormally returns
1b80: 5c 66 42 54 43 4c 5f 4f 4b 5c 66 52 2c 20 74 68 \fBTCL_OK\fR, th
1b90: 6f 75 67 68 20 69 66 20 69 74 20 63 61 6e 6e 6f ough if it canno
1ba0: 74 0a 61 6c 6c 6f 63 61 74 65 20 73 75 66 66 69 t.allocate suffi
1bb0: 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 cient memory to
1bc0: 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 hold the resulti
1bd0: 6e 67 20 69 6d 61 67 65 2c 20 5c 66 42 54 43 4c ng image, \fBTCL
1be0: 5f 45 52 52 4f 52 5c 66 52 20 69 73 0a 72 65 74 _ERROR\fR is.ret
1bf0: 75 72 6e 65 64 20 69 6e 73 74 65 61 64 20 61 6e urned instead an
1c00: 64 2c 20 69 66 20 74 68 65 20 5c 66 49 69 6e 74 d, if the \fIint
1c10: 65 72 70 5c 66 52 20 61 72 67 75 6d 65 6e 74 20 erp\fR argument
1c20: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2c 20 61 6e 0a is non-NULL, an.
1c30: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 error message is
1c40: 20 70 6c 61 63 65 64 20 69 6e 20 74 68 65 20 69 placed in the i
1c50: 6e 74 65 72 70 72 65 74 65 72 27 73 20 72 65 73 nterpreter's res
1c60: 75 6c 74 2e 0a 2e 50 50 0a 5c 66 42 54 6b 5f 50 ult...PP.\fBTk_P
1c70: 68 6f 74 6f 50 75 74 5a 6f 6f 6d 65 64 42 6c 6f hotoPutZoomedBlo
1c80: 63 6b 5c 66 52 20 77 6f 72 6b 73 20 6c 69 6b 65 ck\fR works like
1c90: 20 5c 66 42 54 6b 5f 50 68 6f 74 6f 50 75 74 42 \fBTk_PhotoPutB
1ca0: 6c 6f 63 6b 5c 66 52 20 65 78 63 65 70 74 20 74 lock\fR except t
1cb0: 68 61 74 0a 74 68 65 20 69 6d 61 67 65 20 63 61 hat.the image ca
1cc0: 6e 20 62 65 20 72 65 64 75 63 65 64 20 6f 72 20 n be reduced or
1cd0: 65 6e 6c 61 72 67 65 64 20 66 6f 72 20 64 69 73 enlarged for dis
1ce0: 70 6c 61 79 2e 20 20 54 68 65 0a 5c 66 49 73 75 play. The.\fIsu
1cf0: 62 73 61 6d 70 6c 65 58 5c 66 52 20 61 6e 64 20 bsampleX\fR and
1d00: 5c 66 49 73 75 62 73 61 6d 70 6c 65 59 5c 66 52 \fIsubsampleY\fR
1d10: 20 70 61 72 61 6d 65 74 65 72 73 20 61 6c 6c 6f parameters allo
1d20: 77 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 w the size of th
1d30: 65 0a 69 6d 61 67 65 20 74 6f 20 62 65 20 72 65 e.image to be re
1d40: 64 75 63 65 64 20 62 79 20 73 75 62 73 61 6d 70 duced by subsamp
1d50: 6c 69 6e 67 2e 0a 5c 66 42 54 6b 5f 50 68 6f 74 ling..\fBTk_Phot
1d60: 6f 50 75 74 5a 6f 6f 6d 65 64 42 6c 6f 63 6b 5c oPutZoomedBlock\
1d70: 66 52 20 77 69 6c 6c 20 75 73 65 20 6f 6e 6c 79 fR will use only
1d80: 20 70 69 78 65 6c 73 20 66 72 6f 6d 20 74 68 65 pixels from the
1d90: 20 69 6e 70 75 74 20 69 6d 61 67 65 0a 77 68 6f input image.who
1da0: 73 65 20 58 20 63 6f 6f 72 64 69 6e 61 74 65 73 se X coordinates
1db0: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 73 20 6f are multiples o
1dc0: 66 20 5c 66 49 73 75 62 73 61 6d 70 6c 65 58 5c f \fIsubsampleX\
1dd0: 66 52 2c 20 61 6e 64 20 77 68 6f 73 65 20 59 0a fR, and whose Y.
1de0: 63 6f 6f 72 64 69 6e 61 74 65 73 20 61 72 65 20 coordinates are
1df0: 6d 75 6c 74 69 70 6c 65 73 20 6f 66 20 5c 66 49 multiples of \fI
1e00: 73 75 62 73 61 6d 70 6c 65 59 5c 66 52 2e 20 20 subsampleY\fR.
1e10: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 For example, an
1e20: 69 6d 61 67 65 0a 6f 66 20 35 31 32 78 35 31 32 image.of 512x512
1e30: 20 70 69 78 65 6c 73 20 63 61 6e 20 62 65 20 72 pixels can be r
1e40: 65 64 75 63 65 64 20 74 6f 20 32 35 36 78 32 35 educed to 256x25
1e50: 36 20 62 79 20 73 65 74 74 69 6e 67 0a 5c 66 49 6 by setting.\fI
1e60: 73 75 62 73 61 6d 70 6c 65 58 5c 66 52 20 61 6e subsampleX\fR an
1e70: 64 20 5c 66 49 73 75 62 73 61 6d 70 6c 65 59 5c d \fIsubsampleY\
1e80: 66 52 20 74 6f 20 32 2e 0a 2e 50 50 0a 54 68 65 fR to 2...PP.The
1e90: 20 5c 66 49 7a 6f 6f 6d 58 5c 66 52 20 61 6e 64 \fIzoomX\fR and
1ea0: 20 5c 66 49 7a 6f 6f 6d 59 5c 66 52 20 70 61 72 \fIzoomY\fR par
1eb0: 61 6d 65 74 65 72 73 20 61 6c 6c 6f 77 20 74 68 ameters allow th
1ec0: 65 20 69 6d 61 67 65 20 74 6f 20 62 65 0a 65 6e e image to be.en
1ed0: 6c 61 72 67 65 64 20 62 79 20 70 69 78 65 6c 20 larged by pixel
1ee0: 72 65 70 6c 69 63 61 74 69 6f 6e 2e 20 20 45 61 replication. Ea
1ef0: 63 68 20 70 69 78 65 6c 20 6f 66 20 74 68 65 20 ch pixel of the
1f00: 28 70 6f 73 73 69 62 6c 79 20 73 75 62 73 61 6d (possibly subsam
1f10: 70 6c 65 64 29 0a 69 6e 70 75 74 20 69 6d 61 67 pled).input imag
1f20: 65 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 e will be writte
1f30: 6e 20 74 6f 20 61 20 62 6c 6f 63 6b 20 5c 66 49 n to a block \fI
1f40: 7a 6f 6f 6d 58 5c 66 52 20 70 69 78 65 6c 73 20 zoomX\fR pixels
1f50: 77 69 64 65 20 61 6e 64 0a 5c 66 49 7a 6f 6f 6d wide and.\fIzoom
1f60: 59 5c 66 52 20 70 69 78 65 6c 73 20 68 69 67 68 Y\fR pixels high
1f70: 20 6f 66 20 74 68 65 20 64 69 73 70 6c 61 79 65 of the displaye
1f80: 64 20 69 6d 61 67 65 2e 20 20 53 75 62 73 61 6d d image. Subsam
1f90: 70 6c 69 6e 67 20 61 6e 64 0a 7a 6f 6f 6d 69 6e pling and.zoomin
1fa0: 67 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f g can be used to
1fb0: 67 65 74 68 65 72 20 66 6f 72 20 73 70 65 63 69 gether for speci
1fc0: 61 6c 20 65 66 66 65 63 74 73 2e 0a 2e 50 50 0a al effects...PP.
1fd0: 5c 66 42 54 6b 5f 50 68 6f 74 6f 47 65 74 49 6d \fBTk_PhotoGetIm
1fe0: 61 67 65 5c 66 52 20 63 61 6e 20 62 65 20 75 73 age\fR can be us
1ff0: 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 69 ed to retrieve i
2000: 6d 61 67 65 20 64 61 74 61 20 66 72 6f 6d 20 61 mage data from a
2010: 20 70 68 6f 74 6f 0a 69 6d 61 67 65 2e 20 20 5c photo.image. \
2020: 66 42 54 6b 5f 50 68 6f 74 6f 47 65 74 49 6d 61 fBTk_PhotoGetIma
2030: 67 65 5c 66 52 20 66 69 6c 6c 73 0a 69 6e 20 74 ge\fR fills.in t
2040: 68 65 20 73 74 72 75 63 74 75 72 65 20 70 6f 69 he structure poi
2050: 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 5c nted to by the \
2060: 66 49 62 6c 6f 63 6b 50 74 72 5c 66 52 20 70 61 fIblockPtr\fR pa
2070: 72 61 6d 65 74 65 72 20 77 69 74 68 20 76 61 6c rameter with val
2080: 75 65 73 0a 74 68 61 74 20 64 65 73 63 72 69 62 ues.that describ
2090: 65 20 74 68 65 20 61 64 64 72 65 73 73 20 61 6e e the address an
20a0: 64 20 6c 61 79 6f 75 74 20 6f 66 20 74 68 65 20 d layout of the
20b0: 69 6d 61 67 65 20 64 61 74 61 20 74 68 61 74 20 image data that
20c0: 74 68 65 0a 70 68 6f 74 6f 20 69 6d 61 67 65 20 the.photo image
20d0: 68 61 73 20 73 74 6f 72 65 64 20 69 6e 74 65 72 has stored inter
20e0: 6e 61 6c 6c 79 2e 20 20 54 68 65 20 76 61 6c 75 nally. The valu
20f0: 65 73 20 61 72 65 20 76 61 6c 69 64 0a 75 6e 74 es are valid.unt
2100: 69 6c 20 74 68 65 20 69 6d 61 67 65 20 69 73 20 il the image is
2110: 64 65 73 74 72 6f 79 65 64 20 6f 72 20 69 74 73 destroyed or its
2120: 20 73 69 7a 65 20 69 73 20 63 68 61 6e 67 65 64 size is changed
2130: 2e 0a 2e 50 50 0a 49 74 20 69 73 20 70 6f 73 73 ...PP.It is poss
2140: 69 62 6c 65 20 74 6f 20 6d 6f 64 69 66 79 20 61 ible to modify a
2150: 6e 20 69 6d 61 67 65 20 62 79 20 77 72 69 74 69 n image by writi
2160: 6e 67 20 64 69 72 65 63 74 6c 79 20 74 6f 20 74 ng directly to t
2170: 68 65 20 64 61 74 61 0a 74 68 65 20 5c 66 49 70 he data.the \fIp
2180: 69 78 65 6c 50 74 72 5c 66 52 20 66 69 65 6c 64 ixelPtr\fR field
2190: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 65 20 points to. The
21a0: 73 69 7a 65 20 6f 66 20 74 68 65 20 69 6d 61 67 size of the imag
21b0: 65 20 63 61 6e 6e 6f 74 20 62 65 0a 63 68 61 6e e cannot be.chan
21c0: 67 65 64 20 74 68 69 73 20 77 61 79 2c 20 74 68 ged this way, th
21d0: 6f 75 67 68 2e 0a 41 6c 73 6f 2c 20 63 68 61 6e ough..Also, chan
21e0: 67 65 73 20 6d 61 64 65 20 62 79 20 77 72 69 74 ges made by writ
21f0: 69 6e 67 20 64 69 72 65 63 74 6c 79 20 74 6f 20 ing directly to
2200: 5c 66 49 70 69 78 65 6c 50 74 72 5c 66 52 20 77 \fIpixelPtr\fR w
2210: 69 6c 6c 20 6e 6f 74 20 62 65 0a 69 6d 6d 65 64 ill not be.immed
2220: 69 61 74 65 6c 79 20 76 69 73 69 62 6c 65 2c 20 iately visible,
2230: 62 75 74 20 6f 6e 6c 79 20 61 66 74 65 72 20 61 but only after a
2240: 20 63 61 6c 6c 20 74 6f 0a 5c 66 42 54 6b 5f 49 call to.\fBTk_I
2250: 6d 61 67 65 43 68 61 6e 67 65 64 5c 66 52 20 6f mageChanged\fR o
2260: 72 20 61 66 74 65 72 20 61 6e 20 65 76 65 6e 74 r after an event
2270: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 that causes the
2280: 20 69 6e 74 65 72 65 73 74 65 64 0a 77 69 64 67 interested.widg
2290: 65 74 73 20 74 6f 20 72 65 64 72 61 77 20 74 68 ets to redraw th
22a0: 65 6d 73 65 6c 76 65 73 2e 0a 46 6f 72 20 74 68 emselves..For th
22b0: 65 73 65 20 72 65 61 73 6f 6e 73 20 75 73 75 61 ese reasons usua
22c0: 6c 6c 79 20 69 74 20 69 73 20 70 72 65 66 65 72 lly it is prefer
22d0: 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 63 68 61 able to make cha
22e0: 6e 67 65 73 20 74 6f 0a 61 20 63 6f 70 79 20 6f nges to.a copy o
22f0: 66 20 74 68 65 20 69 6d 61 67 65 20 64 61 74 61 f the image data
2300: 20 61 6e 64 20 77 72 69 74 65 20 69 74 20 62 61 and write it ba
2310: 63 6b 20 77 69 74 68 0a 5c 66 42 54 6b 5f 50 68 ck with.\fBTk_Ph
2320: 6f 74 6f 50 75 74 42 6c 6f 63 6b 5c 66 52 20 6f otoPutBlock\fR o
2330: 72 20 5c 66 42 54 6b 5f 50 68 6f 74 6f 50 75 74 r \fBTk_PhotoPut
2340: 5a 6f 6f 6d 65 64 42 6c 6f 63 6b 5c 66 52 2e 0a ZoomedBlock\fR..
2350: 2e 50 50 0a 5c 66 42 54 6b 5f 50 68 6f 74 6f 47 .PP.\fBTk_PhotoG
2360: 65 74 49 6d 61 67 65 5c 66 52 20 72 65 74 75 72 etImage\fR retur
2370: 6e 73 20 31 20 66 6f 72 20 63 6f 6d 70 61 74 69 ns 1 for compati
2380: 62 69 6c 69 74 79 20 77 69 74 68 20 74 68 65 0a bility with the.
2390: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 corresponding pr
23a0: 6f 63 65 64 75 72 65 20 69 6e 20 74 68 65 20 6f ocedure in the o
23b0: 6c 64 20 70 68 6f 74 6f 20 77 69 64 67 65 74 2e ld photo widget.
23c0: 0a 2e 50 50 0a 5c 66 42 54 6b 5f 50 68 6f 74 6f ..PP.\fBTk_Photo
23d0: 42 6c 61 6e 6b 5c 66 52 20 62 6c 61 6e 6b 73 20 Blank\fR blanks
23e0: 74 68 65 20 65 6e 74 69 72 65 20 61 72 65 61 20 the entire area
23f0: 6f 66 20 74 68 65 0a 70 68 6f 74 6f 20 69 6d 61 of the.photo ima
2400: 67 65 2e 20 20 42 6c 61 6e 6b 20 61 72 65 61 73 ge. Blank areas
2410: 20 6f 66 20 61 20 70 68 6f 74 6f 20 69 6d 61 67 of a photo imag
2420: 65 20 61 72 65 20 74 72 61 6e 73 70 61 72 65 6e e are transparen
2430: 74 2e 0a 2e 50 50 0a 5c 66 42 54 6b 5f 50 68 6f t...PP.\fBTk_Pho
2440: 74 6f 45 78 70 61 6e 64 5c 66 52 20 72 65 71 75 toExpand\fR requ
2450: 65 73 74 73 20 74 68 61 74 20 74 68 65 20 77 69 ests that the wi
2460: 64 67 65 74 27 73 20 69 6d 61 67 65 20 62 65 20 dget's image be
2470: 65 78 70 61 6e 64 65 64 20 74 6f 20 62 65 0a 61 expanded to be.a
2480: 74 20 6c 65 61 73 74 20 5c 66 49 77 69 64 74 68 t least \fIwidth
2490: 5c 66 52 20 78 20 5c 66 49 68 65 69 67 68 74 5c \fR x \fIheight\
24a0: 66 52 20 70 69 78 65 6c 73 20 69 6e 20 73 69 7a fR pixels in siz
24b0: 65 2e 20 20 54 68 65 20 77 69 64 74 68 20 61 6e e. The width an
24c0: 64 2f 6f 72 0a 68 65 69 67 68 74 20 61 72 65 20 d/or.height are
24d0: 75 6e 63 68 61 6e 67 65 64 20 69 66 20 74 68 65 unchanged if the
24e0: 20 75 73 65 72 20 68 61 73 20 73 70 65 63 69 66 user has specif
24f0: 69 65 64 20 61 6e 20 65 78 70 6c 69 63 69 74 20 ied an explicit
2500: 69 6d 61 67 65 20 77 69 64 74 68 0a 6f 72 20 68 image width.or h
2510: 65 69 67 68 74 20 77 69 74 68 20 74 68 65 20 5c eight with the \
2520: 66 42 5c 2d 77 69 64 74 68 5c 66 52 20 61 6e 64 fB\-width\fR and
2530: 2f 6f 72 20 5c 66 42 5c 2d 68 65 69 67 68 74 5c /or \fB\-height\
2540: 66 52 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e fR configuration
2550: 0a 6f 70 74 69 6f 6e 73 2c 20 72 65 73 70 65 63 .options, respec
2560: 74 69 76 65 6c 79 2e 0a 49 66 20 74 68 65 20 69 tively..If the i
2570: 6d 61 67 65 20 64 61 74 61 0a 61 72 65 20 62 65 mage data.are be
2580: 69 6e 67 20 73 75 70 70 6c 69 65 64 20 69 6e 20 ing supplied in
2590: 6d 61 6e 79 20 73 6d 61 6c 6c 20 62 6c 6f 63 6b many small block
25a0: 73 2c 20 69 74 20 69 73 20 6d 6f 72 65 20 65 66 s, it is more ef
25b0: 66 69 63 69 65 6e 74 20 74 6f 20 75 73 65 0a 5c ficient to use.\
25c0: 66 42 54 6b 5f 50 68 6f 74 6f 45 78 70 61 6e 64 fBTk_PhotoExpand
25d0: 5c 66 52 20 6f 72 20 5c 66 42 54 6b 5f 50 68 6f \fR or \fBTk_Pho
25e0: 74 6f 53 65 74 53 69 7a 65 5c 66 52 20 61 74 20 toSetSize\fR at
25f0: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 72 61 the beginning ra
2600: 74 68 65 72 20 74 68 61 6e 0a 61 6c 6c 6f 77 69 ther than.allowi
2610: 6e 67 20 74 68 65 20 69 6d 61 67 65 20 74 6f 20 ng the image to
2620: 65 78 70 61 6e 64 20 69 6e 20 6d 61 6e 79 20 73 expand in many s
2630: 6d 61 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 73 20 mall increments
2640: 61 73 20 69 6d 61 67 65 20 62 6c 6f 63 6b 73 0a as image blocks.
2650: 61 72 65 20 73 75 70 70 6c 69 65 64 2e 0a 2e 50 are supplied...P
2660: 50 0a 5c 66 42 54 6b 5f 50 68 6f 74 6f 45 78 70 P.\fBTk_PhotoExp
2670: 61 6e 64 5c 66 52 20 6e 6f 72 6d 61 6c 6c 79 20 and\fR normally
2680: 72 65 74 75 72 6e 73 20 5c 66 42 54 43 4c 5f 4f returns \fBTCL_O
2690: 4b 5c 66 52 2c 20 74 68 6f 75 67 68 20 69 66 20 K\fR, though if
26a0: 69 74 20 63 61 6e 6e 6f 74 0a 61 6c 6c 6f 63 61 it cannot.alloca
26b0: 74 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 te sufficient me
26c0: 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
26d0: 20 72 65 73 75 6c 74 69 6e 67 20 69 6d 61 67 65 resulting image
26e0: 2c 20 5c 66 42 54 43 4c 5f 45 52 52 4f 52 5c 66 , \fBTCL_ERROR\f
26f0: 52 20 69 73 0a 72 65 74 75 72 6e 65 64 20 69 6e R is.returned in
2700: 73 74 65 61 64 20 61 6e 64 2c 20 69 66 20 74 68 stead and, if th
2710: 65 20 5c 66 49 69 6e 74 65 72 70 5c 66 52 20 61 e \fIinterp\fR a
2720: 72 67 75 6d 65 6e 74 20 69 73 20 6e 6f 6e 2d 4e rgument is non-N
2730: 55 4c 4c 2c 20 61 6e 0a 65 72 72 6f 72 20 6d 65 ULL, an.error me
2740: 73 73 61 67 65 20 69 73 20 70 6c 61 63 65 64 20 ssage is placed
2750: 69 6e 20 74 68 65 20 69 6e 74 65 72 70 72 65 74 in the interpret
2760: 65 72 27 73 20 72 65 73 75 6c 74 2e 0a 2e 50 50 er's result...PP
2770: 0a 5c 66 42 54 6b 5f 50 68 6f 74 6f 53 65 74 53 .\fBTk_PhotoSetS
2780: 69 7a 65 5c 66 52 20 73 70 65 63 69 66 69 65 73 ize\fR specifies
2790: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
27a0: 20 69 6d 61 67 65 2c 20 61 73 20 69 66 20 74 68 image, as if th
27b0: 65 20 75 73 65 72 0a 68 61 64 20 73 70 65 63 69 e user.had speci
27c0: 66 69 65 64 20 74 68 65 20 67 69 76 65 6e 20 5c fied the given \
27d0: 66 49 77 69 64 74 68 5c 66 52 20 61 6e 64 20 5c fIwidth\fR and \
27e0: 66 49 68 65 69 67 68 74 5c 66 52 20 76 61 6c 75 fIheight\fR valu
27f0: 65 73 20 74 6f 20 74 68 65 0a 5c 66 42 5c 2d 77 es to the.\fB\-w
2800: 69 64 74 68 5c 66 52 20 61 6e 64 20 5c 66 42 5c idth\fR and \fB\
2810: 2d 68 65 69 67 68 74 5c 66 52 20 63 6f 6e 66 69 -height\fR confi
2820: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
2830: 2e 20 20 41 20 76 61 6c 75 65 20 6f 66 0a 7a 65 . A value of.ze
2840: 72 6f 20 66 6f 72 20 5c 66 49 77 69 64 74 68 5c ro for \fIwidth\
2850: 66 52 20 6f 72 20 5c 66 49 68 65 69 67 68 74 5c fR or \fIheight\
2860: 66 52 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e fR does not chan
2870: 67 65 20 74 68 65 20 69 6d 61 67 65 27 73 20 77 ge the image's w
2880: 69 64 74 68 0a 6f 72 20 68 65 69 67 68 74 2c 20 idth.or height,
2890: 62 75 74 20 61 6c 6c 6f 77 73 20 74 68 65 20 77 but allows the w
28a0: 69 64 74 68 20 6f 72 20 68 65 69 67 68 74 20 74 idth or height t
28b0: 6f 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 o be changed by
28c0: 73 75 62 73 65 71 75 65 6e 74 0a 63 61 6c 6c 73 subsequent.calls
28d0: 20 74 6f 20 5c 66 42 54 6b 5f 50 68 6f 74 6f 50 to \fBTk_PhotoP
28e0: 75 74 42 6c 6f 63 6b 5c 66 52 2c 20 5c 66 42 54 utBlock\fR, \fBT
28f0: 6b 5f 50 68 6f 74 6f 50 75 74 5a 6f 6f 6d 65 64 k_PhotoPutZoomed
2900: 42 6c 6f 63 6b 5c 66 52 20 6f 72 0a 5c 66 42 54 Block\fR or.\fBT
2910: 6b 5f 50 68 6f 74 6f 45 78 70 61 6e 64 5c 66 52 k_PhotoExpand\fR
2920: 2e 0a 2e 50 50 0a 5c 66 42 54 6b 5f 50 68 6f 74 ...PP.\fBTk_Phot
2930: 6f 53 65 74 53 69 7a 65 5c 66 52 20 6e 6f 72 6d oSetSize\fR norm
2940: 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 5c 66 42 ally returns \fB
2950: 54 43 4c 5f 4f 4b 5c 66 52 2c 20 74 68 6f 75 67 TCL_OK\fR, thoug
2960: 68 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 0a 61 h if it cannot.a
2970: 6c 6c 6f 63 61 74 65 20 73 75 66 66 69 63 69 65 llocate sufficie
2980: 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c nt memory to hol
2990: 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 d the resulting
29a0: 69 6d 61 67 65 2c 20 5c 66 42 54 43 4c 5f 45 52 image, \fBTCL_ER
29b0: 52 4f 52 5c 66 52 20 69 73 0a 72 65 74 75 72 6e ROR\fR is.return
29c0: 65 64 20 69 6e 73 74 65 61 64 20 61 6e 64 2c 20 ed instead and,
29d0: 69 66 20 74 68 65 20 5c 66 49 69 6e 74 65 72 70 if the \fIinterp
29e0: 5c 66 52 20 61 72 67 75 6d 65 6e 74 20 69 73 20 \fR argument is
29f0: 6e 6f 6e 2d 4e 55 4c 4c 2c 20 61 6e 0a 65 72 72 non-NULL, an.err
2a00: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 70 6c or message is pl
2a10: 61 63 65 64 20 69 6e 20 74 68 65 20 69 6e 74 65 aced in the inte
2a20: 72 70 72 65 74 65 72 27 73 20 72 65 73 75 6c 74 rpreter's result
2a30: 2e 0a 2e 50 50 0a 5c 66 42 54 6b 5f 50 68 6f 74 ...PP.\fBTk_Phot
2a40: 6f 47 65 74 53 69 7a 65 5c 66 52 20 72 65 74 75 oGetSize\fR retu
2a50: 72 6e 73 20 74 68 65 20 64 69 6d 65 6e 73 69 6f rns the dimensio
2a60: 6e 73 20 6f 66 20 74 68 65 20 69 6d 61 67 65 20 ns of the image
2a70: 69 6e 0a 2a 5c 66 49 77 69 64 74 68 50 74 72 5c in.*\fIwidthPtr\
2a80: 66 52 20 61 6e 64 20 2a 5c 66 49 68 65 69 67 68 fR and *\fIheigh
2a90: 74 50 74 72 5c 66 52 2e 0a 2e 53 48 20 50 4f 52 tPtr\fR...SH POR
2aa0: 54 41 42 49 4c 49 54 59 0a 2e 50 50 0a 49 6e 20 TABILITY..PP.In
2ab0: 54 6b 20 38 2e 33 20 61 6e 64 20 65 61 72 6c 69 Tk 8.3 and earli
2ac0: 65 72 2c 20 5c 66 42 54 6b 5f 50 68 6f 74 6f 50 er, \fBTk_PhotoP
2ad0: 75 74 42 6c 6f 63 6b 5c 66 52 20 61 6e 64 0a 5c utBlock\fR and.\
2ae0: 66 42 54 6b 5f 50 68 6f 74 6f 50 75 74 5a 6f 6f fBTk_PhotoPutZoo
2af0: 6d 65 64 42 6c 6f 63 6b 5c 66 52 20 68 61 64 20 medBlock\fR had
2b00: 64 69 66 66 65 72 65 6e 74 20 73 69 67 6e 61 74 different signat
2b10: 75 72 65 73 2e 20 49 66 20 79 6f 75 20 77 61 6e ures. If you wan
2b20: 74 20 74 6f 0a 63 6f 6d 70 69 6c 65 20 63 6f 64 t to.compile cod
2b30: 65 20 74 68 61 74 20 75 73 65 73 20 74 68 65 20 e that uses the
2b40: 6f 6c 64 20 69 6e 74 65 72 66 61 63 65 20 61 67 old interface ag
2b50: 61 69 6e 73 74 20 38 2e 34 20 77 69 74 68 6f 75 ainst 8.4 withou
2b60: 74 20 75 70 64 61 74 69 6e 67 0a 79 6f 75 72 20 t updating.your
2b70: 63 6f 64 65 2c 20 63 6f 6d 70 69 6c 65 20 69 74 code, compile it
2b80: 20 77 69 74 68 20 74 68 65 20 66 6c 61 67 0a 2d with the flag.-
2b90: 44 55 53 45 5f 43 4f 4d 50 4f 53 49 54 45 4c 45 DUSE_COMPOSITELE
2ba0: 53 53 5f 50 48 4f 54 4f 5f 50 55 54 5f 42 4c 4f SS_PHOTO_PUT_BLO
2bb0: 43 4b 2e 20 20 43 6f 64 65 20 6c 69 6e 6b 65 64 CK. Code linked
2bc0: 20 75 73 69 6e 67 20 53 74 75 62 73 20 61 67 61 using Stubs aga
2bd0: 69 6e 73 74 0a 6f 6c 64 65 72 20 76 65 72 73 69 inst.older versi
2be0: 6f 6e 73 20 6f 66 20 54 6b 20 77 69 6c 6c 20 63 ons of Tk will c
2bf0: 6f 6e 74 69 6e 75 65 20 74 6f 20 77 6f 72 6b 2e ontinue to work.
2c00: 0a 2e 50 50 0a 49 6e 20 54 6b 20 38 2e 34 2c 20 ..PP.In Tk 8.4,
2c10: 5c 66 42 54 6b 5f 50 68 6f 74 6f 50 75 74 42 6c \fBTk_PhotoPutBl
2c20: 6f 63 6b 5c 66 52 2c 20 5c 66 42 54 6b 5f 50 68 ock\fR, \fBTk_Ph
2c30: 6f 74 6f 50 75 74 5a 6f 6f 6d 65 64 42 6c 6f 63 otoPutZoomedBloc
2c40: 6b 5c 66 52 2c 0a 5c 66 42 54 6b 5f 50 68 6f 74 k\fR,.\fBTk_Phot
2c50: 6f 45 78 70 61 6e 64 5c 66 52 20 61 6e 64 20 5c oExpand\fR and \
2c60: 66 42 54 6b 5f 50 68 6f 74 6f 53 65 74 53 69 7a fBTk_PhotoSetSiz
2c70: 65 5c 66 52 20 64 69 64 20 6e 6f 74 20 74 61 6b e\fR did not tak
2c80: 65 20 61 6e 0a 5c 66 49 69 6e 74 65 72 70 5c 66 e an.\fIinterp\f
2c90: 52 20 61 72 67 75 6d 65 6e 74 20 6f 72 20 72 65 R argument or re
2ca0: 74 75 72 6e 20 61 6e 79 20 72 65 73 75 6c 74 20 turn any result
2cb0: 63 6f 64 65 2e 20 20 49 66 20 69 6e 73 75 66 66 code. If insuff
2cc0: 69 63 69 65 6e 74 0a 6d 65 6d 6f 72 79 20 77 61 icient.memory wa
2cd0: 73 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 s available for
2ce0: 61 6e 20 69 6d 61 67 65 2c 20 54 6b 20 77 6f 75 an image, Tk wou
2cf0: 6c 64 20 70 61 6e 69 63 2e 20 20 54 68 69 73 20 ld panic. This
2d00: 62 65 68 61 76 69 6f 75 72 20 69 73 0a 73 74 69 behaviour is.sti
2d10: 6c 6c 20 73 75 70 70 6f 72 74 65 64 20 69 66 20 ll supported if
2d20: 79 6f 75 20 63 6f 6d 70 69 6c 65 20 79 6f 75 72 you compile your
2d30: 20 65 78 74 65 6e 73 69 6f 6e 20 77 69 74 68 20 extension with
2d40: 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 the additional f
2d50: 6c 61 67 0a 2d 44 55 53 45 5f 50 41 4e 49 43 5f lag.-DUSE_PANIC_
2d60: 4f 4e 5f 50 48 4f 54 4f 5f 41 4c 4c 4f 43 5f 46 ON_PHOTO_ALLOC_F
2d70: 41 49 4c 55 52 45 2e 20 20 43 6f 64 65 20 6c 69 AILURE. Code li
2d80: 6e 6b 65 64 20 75 73 69 6e 67 20 53 74 75 62 73 nked using Stubs
2d90: 20 61 67 61 69 6e 73 74 0a 6f 6c 64 65 72 20 76 against.older v
2da0: 65 72 73 69 6f 6e 73 20 6f 66 20 54 6b 20 77 69 ersions of Tk wi
2db0: 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 77 ll continue to w
2dc0: 6f 72 6b 2e 0a 2e 53 48 20 42 55 47 53 0a 54 68 ork...SH BUGS.Th
2dd0: 65 20 5c 66 42 54 6b 5f 50 68 6f 74 6f 49 6d 61 e \fBTk_PhotoIma
2de0: 67 65 42 6c 6f 63 6b 5c 66 52 20 73 74 72 75 63 geBlock\fR struc
2df0: 74 75 72 65 20 75 73 65 64 20 74 6f 20 70 72 6f ture used to pro
2e00: 76 69 64 65 20 69 6d 61 67 65 20 64 61 74 61 20 vide image data
2e10: 74 6f 0a 5c 66 42 54 6b 5f 50 68 6f 74 6f 50 75 to.\fBTk_PhotoPu
2e20: 74 42 6c 6f 63 6b 5c 66 52 20 70 72 6f 6d 69 73 tBlock\fR promis
2e30: 65 73 20 67 72 65 61 74 20 66 6c 65 78 69 62 69 es great flexibi
2e40: 6c 69 74 79 20 69 6e 20 74 68 65 20 6c 61 79 6f lity in the layo
2e50: 75 74 20 6f 66 20 74 68 65 0a 64 61 74 61 20 28 ut of the.data (
2e60: 65 2e 67 2e 20 73 65 70 61 72 61 74 65 20 70 6c e.g. separate pl
2e70: 61 6e 65 73 20 66 6f 72 20 74 68 65 20 72 65 64 anes for the red
2e80: 2c 20 67 72 65 65 6e 2c 20 62 6c 75 65 20 61 6e , green, blue an
2e90: 64 20 61 6c 70 68 61 0a 63 68 61 6e 6e 65 6c 73 d alpha.channels
2ea0: 29 2e 20 20 55 6e 66 6f 72 74 75 6e 61 74 65 6c ). Unfortunatel
2eb0: 79 2c 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 y, the implement
2ec0: 61 74 69 6f 6e 20 66 61 69 6c 73 20 74 6f 20 68 ation fails to h
2ed0: 6f 6c 64 20 74 68 69 73 0a 70 72 6f 6d 69 73 65 old this.promise
2ee0: 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 69 . The problem i
2ef0: 73 20 74 68 61 74 20 74 68 65 20 5c 66 49 70 69 s that the \fIpi
2f00: 78 65 6c 53 69 7a 65 5c 66 52 20 66 69 65 6c 64 xelSize\fR field
2f10: 20 69 73 0a 28 69 6e 63 6f 72 72 65 63 74 6c 79 is.(incorrectly
2f20: 29 20 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d ) used to determ
2f30: 69 6e 65 20 77 68 65 74 68 65 72 20 74 68 65 20 ine whether the
2f40: 69 6d 61 67 65 20 68 61 73 20 61 6e 20 61 6c 70 image has an alp
2f50: 68 61 20 63 68 61 6e 6e 65 6c 2e 0a 43 75 72 72 ha channel..Curr
2f60: 65 6e 74 6c 79 2c 20 69 66 20 74 68 65 20 6f 66 ently, if the of
2f70: 66 73 65 74 20 66 6f 72 20 74 68 65 20 61 6c 70 fset for the alp
2f80: 68 61 20 63 68 61 6e 6e 65 6c 20 69 73 20 67 72 ha channel is gr
2f90: 65 61 74 65 72 20 6f 72 20 65 71 75 61 6c 20 74 eater or equal t
2fa0: 68 61 6e 0a 5c 66 49 70 69 78 65 6c 53 69 7a 65 han.\fIpixelSize
2fb0: 5c 66 52 2c 20 5c 66 42 74 6b 5f 50 68 6f 74 6f \fR, \fBtk_Photo
2fc0: 50 75 74 62 6c 6f 63 6b 5c 66 52 20 61 73 73 75 Putblock\fR assu
2fd0: 6d 65 73 20 6e 6f 20 61 6c 70 68 61 20 64 61 74 mes no alpha dat
2fe0: 61 20 69 73 0a 70 72 65 73 65 6e 74 20 61 6e 64 a is.present and
2ff0: 20 6d 61 6b 65 73 20 74 68 65 20 69 6d 61 67 65 makes the image
3000: 20 66 75 6c 6c 79 20 6f 70 61 71 75 65 2e 20 20 fully opaque.
3010: 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 This means that
3020: 66 6f 72 20 6c 61 79 6f 75 74 73 0a 77 68 65 72 for layouts.wher
3030: 65 20 74 68 65 20 63 68 61 6e 6e 65 6c 73 20 61 e the channels a
3040: 72 65 20 73 65 70 61 72 61 74 65 20 28 6f 72 20 re separate (or
3050: 61 6e 79 20 6f 74 68 65 72 20 65 78 6f 74 69 63 any other exotic
3060: 20 6c 61 79 6f 75 74 20 77 68 65 72 65 0a 5c 66 layout where.\f
3070: 49 70 69 78 65 6c 53 69 7a 65 5c 66 52 20 68 61 IpixelSize\fR ha
3080: 73 20 74 6f 20 62 65 20 73 6d 61 6c 6c 65 72 20 s to be smaller
3090: 74 68 61 6e 20 74 68 65 20 61 6c 70 68 61 20 6f than the alpha o
30a0: 66 66 73 65 74 29 2c 20 74 68 65 20 61 6c 70 68 ffset), the alph
30b0: 61 0a 63 68 61 6e 6e 65 6c 20 77 69 6c 6c 20 6e a.channel will n
30c0: 6f 74 20 62 65 20 72 65 61 64 20 63 6f 72 72 65 ot be read corre
30d0: 63 74 6c 79 2e 20 20 49 6e 20 6f 72 64 65 72 20 ctly. In order
30e0: 74 6f 20 62 65 20 6f 6e 20 74 68 65 20 73 61 66 to be on the saf
30f0: 65 20 73 69 64 65 0a 69 66 20 74 68 69 73 20 69 e side.if this i
3100: 73 73 75 65 20 77 69 6c 6c 20 62 65 20 63 6f 72 ssue will be cor
3110: 72 65 63 74 65 64 20 69 6e 20 61 20 66 75 74 75 rected in a futu
3120: 72 65 20 72 65 6c 65 61 73 65 2c 20 69 74 20 69 re release, it i
3130: 73 20 73 74 72 6f 6e 67 6c 79 0a 72 65 63 6f 6d s strongly.recom
3140: 6d 65 6e 64 65 64 20 79 6f 75 20 61 6c 77 61 79 mended you alway
3150: 73 20 70 72 6f 76 69 64 65 20 61 6c 70 68 61 20 s provide alpha
3160: 64 61 74 61 20 2d 20 65 76 65 6e 20 69 66 20 74 data - even if t
3170: 68 65 20 69 6d 61 67 65 20 68 61 73 20 6e 6f 0a he image has no.
3180: 74 72 61 6e 73 70 61 72 65 6e 63 79 20 2d 20 61 transparency - a
3190: 6e 64 20 6f 6e 6c 79 20 75 73 65 20 74 68 65 20 nd only use the
31a0: 22 73 74 61 6e 64 61 72 64 22 20 6c 61 79 6f 75 "standard" layou
31b0: 74 20 77 69 74 68 20 61 0a 5c 66 49 70 69 78 65 t with a.\fIpixe
31c0: 6c 53 69 7a 65 5c 66 52 20 6f 66 20 32 20 66 6f lSize\fR of 2 fo
31d0: 72 20 67 72 61 79 73 63 61 6c 65 20 61 6e 64 20 r grayscale and
31e0: 34 20 66 6f 72 20 52 47 42 20 64 61 74 61 20 77 4 for RGB data w
31f0: 69 74 68 0a 5c 66 49 6f 66 66 73 65 74 5c 66 52 ith.\fIoffset\fR
3200: 73 20 6f 66 20 30 2c 20 30 2c 20 30 2c 20 31 20 s of 0, 0, 0, 1
3210: 6f 72 20 30 2c 20 31 2c 20 32 2c 20 33 20 72 65 or 0, 1, 2, 3 re
3220: 73 70 65 63 74 69 76 65 6c 79 2e 0a 2e 53 48 20 spectively...SH
3230: 43 52 45 44 49 54 53 0a 2e 50 50 0a 54 68 65 20 CREDITS..PP.The
3240: 63 6f 64 65 20 66 6f 72 20 74 68 65 20 70 68 6f code for the pho
3250: 74 6f 20 69 6d 61 67 65 20 74 79 70 65 20 77 61 to image type wa
3260: 73 20 64 65 76 65 6c 6f 70 65 64 20 62 79 20 50 s developed by P
3270: 61 75 6c 20 4d 61 63 6b 65 72 72 61 73 2c 0a 62 aul Mackerras,.b
3280: 61 73 65 64 20 6f 6e 20 68 69 73 20 65 61 72 6c ased on his earl
3290: 69 65 72 20 70 68 6f 74 6f 20 77 69 64 67 65 74 ier photo widget
32a0: 20 63 6f 64 65 2e 0a 2e 53 48 20 4b 45 59 57 4f code...SH KEYWO
32b0: 52 44 53 0a 70 68 6f 74 6f 2c 20 69 6d 61 67 65 RDS.photo, image
32c0: 0a .
