util/X86LINUX64/man/man3/Tk_PhotoPutZoomedBlock.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 .TH Tk_FindPhoto 3 8.0 Tk "Tk Library Procedures"
  13 .\" The -*- nroff -*- definitions below are for supplemental macros used
  14 .\" in Tcl/Tk manual entries.
  15 .\"
  16 .\" .AP type name in/out ?indent?
  17 .\"     Start paragraph describing an argument to a library procedure.
  18 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  19 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  20 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  21 .\"     needed;  use .AS below instead)
  22 .\"
  23 .\" .AS ?type? ?name?
  24 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  25 .\"     name are examples of largest possible arguments that will be passed
  26 .\"     to .AP later.  If args are omitted, default tab stops are used.
  27 .\"
  28 .\" .BS
  29 .\"     Start box enclosure.  From here until next .BE, everything will be
  30 .\"     enclosed in one large box.
  31 .\"
  32 .\" .BE
  33 .\"     End of box enclosure.
  34 .\"
  35 .\" .CS
  36 .\"     Begin code excerpt.
  37 .\"
  38 .\" .CE
  39 .\"     End code excerpt.
  40 .\"
  41 .\" .VS ?version? ?br?
  42 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  43 .\"     of man pages.  The first argument is ignored and used for recording
  44 .\"     the version when the .VS was added, so that the sidebars can be
  45 .\"     found and removed when they reach a certain age.  If another argument
  46 .\"     is present, then a line break is forced before starting the sidebar.
  47 .\"
  48 .\" .VE
  49 .\"     End of vertical sidebar.
  50 .\"
  51 .\" .DS
  52 .\"     Begin an indented unfilled display.
  53 .\"
  54 .\" .DE
  55 .\"     End of indented unfilled display.
  56 .\"
  57 .\" .SO ?manpage?
  58 .\"     Start of list of standard options for a Tk widget. The manpage
  59 .\"     argument defines where to look up the standard options; if
  60 .\"     omitted, defaults to "options". The options follow on successive
  61 .\"     lines, in three columns separated by tabs.
  62 .\"
  63 .\" .SE
  64 .\"     End of list of standard options for a Tk widget.
  65 .\"
  66 .\" .OP cmdName dbName dbClass
  67 .\"     Start of description of a specific option.  cmdName gives the
  68 .\"     option's name as specified in the class command, dbName gives
  69 .\"     the option's name in the option database, and dbClass gives
  70 .\"     the option's class in the option database.
  71 .\"
  72 .\" .UL arg1 arg2
  73 .\"     Print arg1 underlined, then print arg2 normally.
  74 .\"
  75 .\" .QW arg1 ?arg2?
  76 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  77 .\"
  78 .\" .PQ arg1 ?arg2?
  79 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  80 .\"     (for trailing punctuation) and then a closing parenthesis.
  81 .\"
  82 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  83 .if t .wh -1.3i ^B
  84 .nr ^l \n(.l
  85 .ad b
  86 .\"     # Start an argument description
  87 .de AP
  88 .ie !"\\$4"" .TP \\$4
  89 .el \{\
  90 .   ie !"\\$2"" .TP \\n()Cu
  91 .   el          .TP 15
  92 .\}
  93 .ta \\n()Au \\n()Bu
  94 .ie !"\\$3"" \{\
  95 \&\\$1 \\fI\\$2\\fP (\\$3)
  96 .\".b
  97 .\}
  98 .el \{\
  99 .br
 100 .ie !"\\$2"" \{\
 101 \&\\$1  \\fI\\$2\\fP
 102 .\}
 103 .el \{\
 104 \&\\fI\\$1\\fP
 105 .\}
 106 .\}
 107 ..
 108 .\"     # define tabbing values for .AP
 109 .de AS
 110 .nr )A 10n
 111 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 112 .nr )B \\n()Au+15n
 113 .\"
 114 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 115 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 116 ..
 117 .AS Tcl_Interp Tcl_CreateInterp in/out
 118 .\"     # BS - start boxed text
 119 .\"     # ^y = starting y location
 120 .\"     # ^b = 1
 121 .de BS
 122 .br
 123 .mk ^y
 124 .nr ^b 1u
 125 .if n .nf
 126 .if n .ti 0
 127 .if n \l'\\n(.lu\(ul'
 128 .if n .fi
 129 ..
 130 .\"     # BE - end boxed text (draw box now)
 131 .de BE
 132 .nf
 133 .ti 0
 134 .mk ^t
 135 .ie n \l'\\n(^lu\(ul'
 136 .el \{\
 137 .\"     Draw four-sided box normally, but don't draw top of
 138 .\"     box if the box started on an earlier page.
 139 .ie !\\n(^b-1 \{\
 140 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 141 .\}
 142 .el \}\
 143 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 144 .\}
 145 .\}
 146 .fi
 147 .br
 148 .nr ^b 0
 149 ..
 150 .\"     # VS - start vertical sidebar
 151 .\"     # ^Y = starting y location
 152 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 153 .de VS
 154 .if !"\\$2"" .br
 155 .mk ^Y
 156 .ie n 'mc \s12\(br\s0
 157 .el .nr ^v 1u
 158 ..
 159 .\"     # VE - end of vertical sidebar
 160 .de VE
 161 .ie n 'mc
 162 .el \{\
 163 .ev 2
 164 .nf
 165 .ti 0
 166 .mk ^t
 167 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 168 .sp -1
 169 .fi
 170 .ev
 171 .\}
 172 .nr ^v 0
 173 ..
 174 .\"     # Special macro to handle page bottom:  finish off current
 175 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 176 .\"     # page bottom macro.
 177 .de ^B
 178 .ev 2
 179 'ti 0
 180 'nf
 181 .mk ^t
 182 .if \\n(^b \{\
 183 .\"     Draw three-sided box if this is the box's first page,
 184 .\"     draw two sides but no top otherwise.
 185 .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
 186 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 187 .\}
 188 .if \\n(^v \{\
 189 .nr ^x \\n(^tu+1v-\\n(^Yu
 190 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 191 .\}
 192 .bp
 193 'fi
 194 .ev
 195 .if \\n(^b \{\
 196 .mk ^y
 197 .nr ^b 2
 198 .\}
 199 .if \\n(^v \{\
 200 .mk ^Y
 201 .\}
 202 ..
 203 .\"     # DS - begin display
 204 .de DS
 205 .RS
 206 .nf
 207 .sp
 208 ..
 209 .\"     # DE - end display
 210 .de DE
 211 .fi
 212 .RE
 213 .sp
 214 ..
 215 .\"     # SO - start of list of standard options
 216 .de SO
 217 'ie '\\$1'' .ds So \\fBoptions\\fR
 218 'el .ds So \\fB\\$1\\fR
 219 .SH "STANDARD OPTIONS"
 220 .LP
 221 .nf
 222 .ta 5.5c 11c
 223 .ft B
 224 ..
 225 .\"     # SE - end of list of standard options
 226 .de SE
 227 .fi
 228 .ft R
 229 .LP
 230 See the \\*(So manual entry for details on the standard options.
 231 ..
 232 .\"     # OP - start of full description for a single option
 233 .de OP
 234 .LP
 235 .nf
 236 .ta 4c
 237 Command-Line Name:      \\fB\\$1\\fR
 238 Database Name:  \\fB\\$2\\fR
 239 Database Class: \\fB\\$3\\fR
 240 .fi
 241 .IP
 242 ..
 243 .\"     # CS - begin code excerpt
 244 .de CS
 245 .RS
 246 .nf
 247 .ta .25i .5i .75i 1i
 248 ..
 249 .\"     # CE - end code excerpt
 250 .de CE
 251 .fi
 252 .RE
 253 ..
 254 .\"     # UL - underline word
 255 .de UL
 256 \\$1\l'|0\(ul'\\$2
 257 ..
 258 .\"     # QW - apply quotation marks to word
 259 .de QW
 260 .ie '\\*(lq'"' ``\\$1''\\$2
 261 .\"" fix emacs highlighting
 262 .el \\*(lq\\$1\\*(rq\\$2
 263 ..
 264 .\"     # PQ - apply parens and quotation marks to word
 265 .de PQ
 266 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 267 .\"" fix emacs highlighting
 268 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 269 ..
 270 .\"     # QR - quoted range
 271 .de QR
 272 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 273 .\"" fix emacs highlighting
 274 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 275 ..
 276 .\"     # MT - "empty" string
 277 .de MT
 278 .QW ""
 279 ..
 280 .BS
 281 .SH NAME
 282 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.
 283 .SH SYNOPSIS
 284 .nf
 285 \fB#include <tk.h>\fR
 286 .sp
 287 Tk_PhotoHandle
 288 \fBTk_FindPhoto\fR(\fIinterp, imageName\fR)
 289 .sp
 290 int
 291 \fBTk_PhotoPutBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\
 292 compRule\fR)
 293 .sp
 294 int
 295 \fBTk_PhotoPutZoomedBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\
 296 zoomX, zoomY, subsampleX, subsampleY, compRule\fR)
 297 .sp
 298 int
 299 \fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR)
 300 .sp
 301 void
 302 \fBTk_PhotoBlank\fR(\fIhandle\fR)
 303 .sp
 304 int
 305 \fBTk_PhotoExpand\fR(\fIinterp, handle, width, height\fR)
 306 .sp
 307 void
 308 \fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR)
 309 .sp
 310 int
 311 \fBTk_PhotoSetSize\fR(\fIinterp. handle, width, height\fR)
 312 .SH ARGUMENTS
 313 .AS Tk_PhotoImageBlock window_path
 314 .AP Tcl_Interp *interp in
 315 Interpreter in which image was created and in which error reporting is
 316 to be done.
 317 .AP "const char" *imageName in
 318 Name of the photo image.
 319 .AP Tk_PhotoHandle handle in
 320 Opaque handle identifying the photo image to be affected.
 321 .AP Tk_PhotoImageBlock *blockPtr in
 322 Specifies the address and storage layout of image data.
 323 .AP int x in
 324 Specifies the X coordinate where the top-left corner of the block is
 325 to be placed within the image.
 326 .AP int y in
 327 Specifies the Y coordinate where the top-left corner of the block is
 328 to be placed within the image.
 329 .AP int width in
 330 Specifies the width of the image area to be affected (for
 331 \fBTk_PhotoPutBlock\fR) or the desired image width (for
 332 \fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR).
 333 .AP int compRule in
 334 Specifies the compositing rule used when combining transparent pixels
 335 in a block of data with a photo image.  Must be one of
 336 \fBTK_PHOTO_COMPOSITE_OVERLAY\fR (which puts the block of data over the top
 337 of the existing photo image, with the previous contents showing
 338 through in the transparent bits) or \fBTK_PHOTO_COMPOSITE_SET\fR (which
 339 discards the existing photo image contents in the rectangle covered by
 340 the data block.)
 341 .AP int height in
 342 Specifies the height of the image area to be affected (for
 343 \fBTk_PhotoPutBlock\fR) or the desired image height (for
 344 \fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR).
 345 .AP int *widthPtr out
 346 Pointer to location in which to store the image width.
 347 .AP int *heightPtr out
 348 Pointer to location in which to store the image height.
 349 .AP int subsampleX in
 350 Specifies the subsampling factor in the X direction for input
 351 image data.
 352 .AP int subsampleY in
 353 Specifies the subsampling factor in the Y direction for input
 354 image data.
 355 .AP int zoomX in
 356 Specifies the zoom factor to be applied in the X direction to pixels
 357 being written to the photo image.
 358 .AP int zoomY in
 359 Specifies the zoom factor to be applied in the Y direction to pixels
 360 being written to the photo image.
 361 .BE
 362 .SH DESCRIPTION
 363 .PP
 364 \fBTk_FindPhoto\fR returns an opaque handle that is used to identify a
 365 particular photo image to the other procedures.  The parameter is the
 366 name of the image, that is, the name specified to the \fBimage create
 367 photo\fR command, or assigned by that command if no name was specified.
 368 .PP
 369 \fBTk_PhotoPutBlock\fR is used to supply blocks of image data to be
 370 displayed.  The call affects an area of the image of size
 371 \fIwidth\fR x \fIheight\fR pixels, with its top-left corner at
 372 coordinates (\fIx\fR,\fIy\fR).  All of \fIwidth\fR, \fIheight\fR,
 373 \fIx\fR, and \fIy\fR must be non-negative.
 374 If part of this area lies outside the
 375 current bounds of the image, the image will be expanded to include the
 376 area, unless the user has specified an explicit image size with the
 377 \fB\-width\fR and/or \fB\-height\fR widget configuration options
 378 (see photo(n)); in that
 379 case the area is silently clipped to the image boundaries.
 380 .PP
 381 The \fIblock\fR parameter is a pointer to a
 382 \fBTk_PhotoImageBlock\fR structure, defined as follows:
 383 .CS
 384 typedef struct {
 385     unsigned char *\fIpixelPtr\fR;
 386     int \fIwidth\fR;
 387     int \fIheight\fR;
 388     int \fIpitch\fR;
 389     int \fIpixelSize\fR;
 390     int \fIoffset\fR[4];
 391 } \fBTk_PhotoImageBlock\fR;
 392 .CE
 393 The \fIpixelPtr\fR field points to the first pixel, that is, the
 394 top-left pixel in the block.
 395 The \fIwidth\fR and \fIheight\fR fields specify the dimensions of the
 396 block of pixels.  The \fIpixelSize\fR field specifies the address
 397 difference between two horizontally adjacent pixels.  Often it is 3
 398 or 4, but it can have any value.  The \fIpitch\fR field specifies the
 399 address difference between two vertically adjacent pixels.  The
 400 \fIoffset\fR array contains the offsets from the address of a pixel
 401 to the addresses of the bytes containing the red, green, blue and alpha
 402 (transparency) components.  These are normally 0, 1, 2 and 3, but can
 403 have other values, e.g., for images that are stored as separate red,
 404 green and blue planes.
 405 .PP
 406 The \fIcompRule\fR parameter to \fBTk_PhotoPutBlock\fR specifies a
 407 compositing rule that says what to do with transparent pixels.  The
 408 value \fBTK_PHOTO_COMPOSITE_OVERLAY\fR says that the previous contents of
 409 the photo image should show through, and the value
 410 \fBTK_PHOTO_COMPOSITE_SET\fR says that the previous contents of the photo
 411 image should be completely ignored, and the values from the block be
 412 copied directly across.  The behavior in Tk8.3 and earlier was
 413 equivalent to having \fBTK_PHOTO_COMPOSITE_OVERLAY\fR as a compositing rule.
 414 .PP
 415 The value given for the \fIwidth\fR and \fIheight\fR parameters to
 416 \fBTk_PhotoPutBlock\fR do not have to correspond to the values specified
 417 in \fIblock\fR.  If they are smaller, \fBTk_PhotoPutBlock\fR extracts a
 418 sub-block from the image data supplied.  If they are larger, the data
 419 given are replicated (in a tiled fashion) to fill the specified area.
 420 These rules operate independently in the horizontal and vertical
 421 directions.
 422 .PP
 423 \fBTk_PhotoPutBlock\fR normally returns \fBTCL_OK\fR, though if it cannot
 424 allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is
 425 returned instead and, if the \fIinterp\fR argument is non-NULL, an
 426 error message is placed in the interpreter's result.
 427 .PP
 428 \fBTk_PhotoPutZoomedBlock\fR works like \fBTk_PhotoPutBlock\fR except that
 429 the image can be reduced or enlarged for display.  The
 430 \fIsubsampleX\fR and \fIsubsampleY\fR parameters allow the size of the
 431 image to be reduced by subsampling.
 432 \fBTk_PhotoPutZoomedBlock\fR will use only pixels from the input image
 433 whose X coordinates are multiples of \fIsubsampleX\fR, and whose Y
 434 coordinates are multiples of \fIsubsampleY\fR.  For example, an image
 435 of 512x512 pixels can be reduced to 256x256 by setting
 436 \fIsubsampleX\fR and \fIsubsampleY\fR to 2.
 437 .PP
 438 The \fIzoomX\fR and \fIzoomY\fR parameters allow the image to be
 439 enlarged by pixel replication.  Each pixel of the (possibly subsampled)
 440 input image will be written to a block \fIzoomX\fR pixels wide and
 441 \fIzoomY\fR pixels high of the displayed image.  Subsampling and
 442 zooming can be used together for special effects.
 443 .PP
 444 \fBTk_PhotoGetImage\fR can be used to retrieve image data from a photo
 445 image.  \fBTk_PhotoGetImage\fR fills
 446 in the structure pointed to by the \fIblockPtr\fR parameter with values
 447 that describe the address and layout of the image data that the
 448 photo image has stored internally.  The values are valid
 449 until the image is destroyed or its size is changed.
 450 \fBTk_PhotoGetImage\fR returns 1 for compatibility with the
 451 corresponding procedure in the old photo widget.
 452 .PP
 453 \fBTk_PhotoBlank\fR blanks the entire area of the
 454 photo image.  Blank areas of a photo image are transparent.
 455 .PP
 456 \fBTk_PhotoExpand\fR requests that the widget's image be expanded to be
 457 at least \fIwidth\fR x \fIheight\fR pixels in size.  The width and/or
 458 height are unchanged if the user has specified an explicit image width
 459 or height with the \fB\-width\fR and/or \fB\-height\fR configuration
 460 options, respectively.
 461 If the image data
 462 are being supplied in many small blocks, it is more efficient to use
 463 \fBTk_PhotoExpand\fR or \fBTk_PhotoSetSize\fR at the beginning rather than
 464 allowing the image to expand in many small increments as image blocks
 465 are supplied.
 466 .PP
 467 \fBTk_PhotoExpand\fR normally returns \fBTCL_OK\fR, though if it cannot
 468 allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is
 469 returned instead and, if the \fIinterp\fR argument is non-NULL, an
 470 error message is placed in the interpreter's result.
 471 .PP
 472 \fBTk_PhotoSetSize\fR specifies the size of the image, as if the user
 473 had specified the given \fIwidth\fR and \fIheight\fR values to the
 474 \fB\-width\fR and \fB\-height\fR configuration options.  A value of
 475 zero for \fIwidth\fR or \fIheight\fR does not change the image's width
 476 or height, but allows the width or height to be changed by subsequent
 477 calls to \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR or
 478 \fBTk_PhotoExpand\fR.
 479 .PP
 480 \fBTk_PhotoSetSize\fR normally returns \fBTCL_OK\fR, though if it cannot
 481 allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is
 482 returned instead and, if the \fIinterp\fR argument is non-NULL, an
 483 error message is placed in the interpreter's result.
 484 .PP
 485 \fBTk_PhotoGetSize\fR returns the dimensions of the image in
 486 *\fIwidthPtr\fR and *\fIheightPtr\fR.
 487 .SH PORTABILITY
 488 .PP
 489 In Tk 8.3 and earlier, \fBTk_PhotoPutBlock\fR and
 490 \fBTk_PhotoPutZoomedBlock\fR had different signatures. If you want to
 491 compile code that uses the old interface against 8.4 without updating
 492 your code, compile it with the flag
 493 -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK.  Code linked using Stubs against
 494 older versions of Tk will continue to work.
 495 .PP
 496 In Tk 8.4, \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR,
 497 \fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR did not take an
 498 \fIinterp\fR argument or return any result code.  If insufficient
 499 memory was available for an image, Tk would panic.  This behaviour is
 500 still supported if you compile your extension with the additional flag
 501 -DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE.  Code linked using Stubs against
 502 older versions of Tk will continue to work.
 503 .SH CREDITS
 504 .PP
 505 The code for the photo image type was developed by Paul Mackerras,
 506 based on his earlier photo widget code.
 507 .SH KEYWORDS
 508 photo, image