## Tcl9.0.3/Tk9.0.3 Documentation > Tk C API > FindPhoto

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  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.
  SYNOPSIS
    #include <tk.h>
    Tk_PhotoHandle
    Tk_FindPhoto(interp, imageName)
    int
    Tk_PhotoPutBlock(interp, handle, blockPtr, x, y, width, height,
    compRule)
    int
    Tk_PhotoPutZoomedBlock(interp, handle, blockPtr, x, y, width, height,
    zoomX, zoomY, subsampleX, subsampleY, compRule)
    int
    Tk_PhotoGetImage(handle, blockPtr)
    Tk_PhotoBlank(handle)
    int
    Tk_PhotoExpand(interp, handle, width, height)
    Tk_PhotoGetSize(handle, widthPtr, heightPtr)
    int
    Tk_PhotoSetSize(interp. handle, width, height)
  引数 ARGUMENTS
    Tcl_Interp *interp (入力in)
    const char *imageName (入力in)
    Tk_PhotoHandle handle (入力in)
    Tk_PhotoImageBlock *blockPtr (入力in)
    int x (入力in)
    int y (入力in)
    int width (入力in)
    int compRule (入力in)
    int height (入力in)
    int *widthPtr (出力out)
    int *heightPtr (出力out)
    int subsampleX (入力in)
    int subsampleY (入力in)
    int zoomX (入力in)
    int zoomY (入力in)
  説明 DESCRIPTION
  移植性 PORTABILITY
  瑕疵 BUGS
  著作権表示 CREDITS
  KEYWORDS

### 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.

### SYNOPSIS

#include <tk.h>
Tk_PhotoHandle
Tk_FindPhoto(interp, imageName)
int
Tk_PhotoPutBlock(interp, handle, blockPtr, x, y, width, height,
compRule)
int
Tk_PhotoPutZoomedBlock(interp, handle, blockPtr, x, y, width, height,
zoomX, zoomY, subsampleX, subsampleY, compRule)
int
Tk_PhotoGetImage(handle, blockPtr)
Tk_PhotoBlank(handle)
int
Tk_PhotoExpand(interp, handle, width, height)
Tk_PhotoGetSize(handle, widthPtr, heightPtr)
int
Tk_PhotoSetSize(interp. handle, width, height)

### 引数 ARGUMENTS

Tcl_Interp *interp (入力in)
  その中に映像が生成され､不都合報告がされる解釈実行機能｡　 Interpreter in which image was created and in which error reporting is to be done.

const char *imageName (入力in)
  写真映像の名前｡ Name of the photo image.

Tk_PhotoHandle handle (入力in)
  影響を受ける写真映像を識別する不透明な操作子｡ Opaque handle identifying the photo image to be affected.

Tk_PhotoImageBlock *blockPtr (入力in)
  映像データの番地と貯蔵配置を指し示す｡　 Specifies the address and storage layout of image data.

int x (入力in)
  映像の中の､区域の左上隅が置かれる箇所の､ X 座標を指し示す｡ Specifies the X coordinate where the top-left corner of the block is to be placed within the image.

int y (入力in)
  映像の中の､区域の左上隅が置かれる箇所の､ Y 座標を指し示す｡ Specifies the Y coordinate where the top-left corner of the block is to be placed within the image.

int width (入力in)
  影響を受ける映像の巾(Tk_PhotoPutBlockについて)又は､望ましい映像の巾(Tk_PhotoExpand と Tk_PhotoSetSizeについて)を指し示す｡　 Specifies the width of the image area to be affected (for Tk_PhotoPutBlock) or the desired image width (for Tk_PhotoExpand and Tk_PhotoSetSize).

int compRule (入力in)
  写真映像を伴う区域の透明画素の結合に使用する複合規則を指定する｡ TK_PHOTO_COMPOSITE_OVERLAY (既存の写真映像に､透明ビットを通して指し示す以前の内容のデータ区域を被せる)かTK_PHOTO_COMPOSITE_SET (これはデータ区域によって変換された矩形内に含まれる既存の写真映像を棄却する)のいずれかでなければならない｡　 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.)

int height (入力in)
  影響を受ける映像の高さ(Tk_PhotoPutBlockについて)又は､望ましい映像の高さ(Tk_PhotoExpand と Tk_PhotoSetSizeについて)を指し示す｡　 Specifies the height of the image area to be affected (for Tk_PhotoPutBlock) or the desired image height (for Tk_PhotoExpand and Tk_PhotoSetSize).

int *widthPtr (出力out)
  映像巾を保存している場所への指示子｡ Pointer to location in which to store the image width.

int *heightPtr (出力out)
  映像高さを保存している場所への指示子｡ Pointer to location in which to store the image height.

int subsampleX (入力in)
  入力映像データの為の X 方向の採取率係数を指定する｡　 Specifies the subsampling factor in the X direction for input image data.

int subsampleY (入力in)
  入力映像データの為の Y 方向の採取率係数を指定する｡　 Specifies the subsampling factor in the Y direction for input image data.

int zoomX (入力in)
  写真映像に書かれる画素に適用される X 方向の拡大係数を指定する｡ Specifies the zoom factor to be applied in the X direction to pixels being written to the photo image.

int zoomY (入力in)
  写真映像に書かれる画素に適用される Y 方向の拡大係数を指定する｡ Specifies the zoom factor to be applied in the Y direction to pixels being written to the photo image.

### 説明 DESCRIPTION

Tk_FindPhoto は他の手続函数に特定の写真影像を識別するために使われる不透明の処理子を返す｡假引数は影像の名前であり､即ち､ image createphoto 命令に指定される名前であり､もし名前が指定されていない場合はその命令によって代入される｡もし imageName が実在しないか､写真映像の名前ではない場合､ Tk_FindPhoto は NULL を返す｡ Tk_FindPhoto 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 image create photo command, or assigned by that command if no name was specified. If imageName does not exist or is not a photo image, Tk_FindPhoto returns NULL.

Tk_PhotoPutBlock は表示される為の影像データの区域を提供する為に使われる｡呼出しは左上隅が(x,y)で寸法が width × height 画素の影像の領域に影響を及ぼす｡全ての width と height と x と y は非負でなければならない｡もしこの境域の一部が影像の現在の境界の外にあると､影像は使用者が部品構成設定指示項目により明示的に影像の寸法を -width 及び/又は -height によって指定されていない限り､領域を含む様に拡張される( photo(n)参照); その場合､領域は報告なしに影像境界に切詰められる｡ Tk_PhotoPutBlock is used to supply blocks of image data to be displayed. The call affects an area of the image of size width x height pixels, with its top-left corner at coordinates (x,y). All of width, height, x, and y 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 -width and/or -height widget configuration options (see photo(n)); in that case the area is silently clipped to the image boundaries.

block 假引数は Tk_PhotoImageBlock 構造へのポインターであり､次の様に定義される: The block parameter is a pointer to a Tk_PhotoImageBlock structure, defined as follows:

    typedef struct {
        unsigned char *pixelPtr;
        int width;
        int height;
        int pitch;
        int pixelSize;
        int offset[4];
    } Tk_PhotoImageBlock;

pixelPtr 欄は最初の画素を指す､それは区画の左上隅の画素である｡ width 欄と height 欄は画素の区画の寸法を指定する｡ width 欄と height 欄は画素の区画の寸法を指定する｡ pixelSize 欄は水平に隣り合う二つの画素の間の番地の距離を指定する｡ RGB には 4 ､白黒濃淡映像データには 2 である｡偏寄配列内の偏寄がそれに応じていれば(譬ば､赤､緑､青用のデータが別々の面に保存される)それ以外の値も可能である｡但し､その様な整列法の使用は強く批判される｡不具合の種である､もし透明度が与えられると正しく働かないので(下のBUGS 節を参照されたい)｡ pitch 欄は垂直に隣合う２つの画素の番地の距離である｡ offset 配列は､画素の番地から､赤､緑､青､アルファ(透明度)要素を含むバイトの番地迄の画素の番地の偏寄を含む｡もし､赤と緑と青からの偏寄が等しい場合､映像は白黒濃淡として解釈実行される｡もしそれらが異なっている場合､ RGB データが仮定される｡通常､偏寄は RGB データには 0, 1, 2, 3 であり､白黒濃淡画には 0, 0, 0, 1 である｡透明度の偏寄に負の値を設定し pixelSize 欄を適切に調整すれば透明度なしの映像を提供することは可能である｡但しその使用は批判される(BUGS 節を参照されたい)｡　　　 The pixelPtr field points to the first pixel, that is, the top-left pixel in the block. The width and height fields specify the dimensions of the block of pixels. The pixelSize field specifies the address difference between two horizontally adjacent pixels. It should be 4 for RGB and 2 for grayscale image data. Other values are possible, if the offsets in the offset array are adjusted accordingly (e.g. for red, green and blue data stored in different planes). Using such a layout is strongly discouraged, though. Due to a bug, it might not work correctly if an alpha channel is provided. (see the BUGS section below). The pitch field specifies the address difference between two vertically adjacent pixels. The offset 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. If the offsets for red, green and blue are equal, the image is interpreted as grayscale. If they differ, RGB data is assumed. Normally the offsets will be 0, 1, 2, 3 for RGB data and 0, 0, 0, 1 for grayscale. It is possible to provide image data without an alpha channel by setting the offset for alpha to a negative value and adjusting the pixelSize field accordingly. This use is discouraged, though (see the BUGS section below).

Tk_PhotoPutBlock への compRule 假引数は合成規則を指定し､それは画素の移転に何をすべきかを述べる｡値 TK_PHOTO_COMPOSITE_OVERLAY は写真影像の以前の内容は透かして示す事を通知し､又､値 TK_PHOTO_COMPOSITE_SET は写真影像の以前の内容は完全に無視されるべきであり､且つ､区間からの値は横断して複写されるべきことを通知する｡ Tk8.3 版以前の挙動は合成規則として TK_PHOTO_COMPOSITE_OVERLAY をさせることと等価である｡ The compRule parameter to Tk_PhotoPutBlock 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.

Tk_PhotoPutBlock の width と height 假引数として与えられた値は block 内の指定された値に一致しなくてもよい｡もしそれが小さい場合､Tk_PhotoPutBlock は供給された影像データから微小範囲を抽出する｡もしそれが大きい場合､与えら得たデータは指定された領域を満たす為に繰返(貼り合せる様式で)される｡これ等の規則は水平方向と垂直方向に別々に適用される｡ The value given for the width and height parameters to Tk_PhotoPutBlock do not have to correspond to the values specified in block. If they are smaller, Tk_PhotoPutBlock 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.

Tk_PhotoPutBlock は通常 TCL_OK を返すが､結果の影像を保有する充分な記憶域が割当てられない場合､ TCL_ERROR が返され､もし interp 引数が非-NULL の場合不都合伝言文が解釈実行機能の結果に置かれる｡ Tk_PhotoPutBlock normally returns TCL_OK, though if it cannot allocate sufficient memory to hold the resulting image, TCL_ERROR is returned instead and, if the interp argument is non-NULL, an error message is placed in the interpreter's result.

Tk_PhotoPutZoomedBlock は Tk_PhotoPutBlock と同じように働くが違いは､表示の為に影像を減らしたり拡大したりできる｡ subsampleX and subsampleY 假引数は微小採取により影像の寸法を減らすことを許容する｡ Tk_PhotoPutZoomedBlock はその X 座標が subsampleX の倍数且つその Y 座標が subsampleY の倍数である入力影像の画像のみを使用する｡譬えば､ 512×512 画素の影像は subsampleX and subsampleY を 2 に設定して 256×256 に減少することができる｡ Tk_PhotoPutZoomedBlock works like Tk_PhotoPutBlock except that the image can be reduced or enlarged for display. The subsampleX and subsampleY parameters allow the size of the image to be reduced by subsampling. Tk_PhotoPutZoomedBlock will use only pixels from the input image whose X coordinates are multiples of subsampleX, and whose Y coordinates are multiples of subsampleY. For example, an image of 512x512 pixels can be reduced to 256x256 by setting subsampleX and subsampleY to 2.

zoomX と zoomY 假引数は影像に画素繰返しにより拡大を許容する｡入力影像のそれぞれの画素は(可能なら微小採取)表示影像の zoomX 画素巾と zoomY 画素高さの区域に書かれる｡微小採取と拡大は特別の効果の為に一緒に使われる｡ The zoomX and zoomY parameters allow the image to be enlarged by pixel replication. Each pixel of the (possibly subsampled) input image will be written to a block zoomX pixels wide and zoomY pixels high of the displayed image. Subsampling and zooming can be used together for special effects.

Tk_PhotoGetImage は写真影像から影像データを取出すために使うことができる｡Tk_PhotoGetImage は blockPtr 假引数により値が指される構造を満たす､それは写真影像が内部的に保存された影像の番地や割付が記述される｡値は影像が破壊されるかその寸法が変更される迄適切である｡ Tk_PhotoGetImage can be used to retrieve image data from a photo image. Tk_PhotoGetImage fills in the structure pointed to by the blockPtr 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.

pixelPtr 欄が指しているデータを直接書いて映像を修正することも可能である｡但し､この方法では､映像の寸法は変更できない｡又､pixelPtr への直接の書込みによる変更は直ぐには可視化されない､ Tk_ImageChanged への呼出しの後､或いは関連する部品によりそれそのものを再描画することを生じる行事があって後初めて可能になる｡この様な理由により､通常は複写しておいた映像データに変更を加え､ Tk_PhotoPutBlock 又は Tk_PhotoPutZoomedBlock により書き戻す方法が好まれる｡　 It is possible to modify an image by writing directly to the data the pixelPtr field points to. The size of the image cannot be changed this way, though. Also, changes made by writing directly to pixelPtr will not be immediately visible, but only after a call to Tk_ImageChanged or after an event that causes the interested widgets to redraw themselves. For these reasons usually it is preferable to make changes to a copy of the image data and write it back with Tk_PhotoPutBlock or Tk_PhotoPutZoomedBlock.

Tk_PhotoGetImage は古い写真部品内の相当する手続函数に互換性があれば 1 を返す｡ Tk_PhotoGetImage returns 1 for compatibility with the corresponding procedure in the old photo widget.

Tk_PhotoBlank は写真影像の全体の領域を空白にする｡写真影像の空白領域は透明である｡ Tk_PhotoBlank blanks the entire area of the photo image. Blank areas of a photo image are transparent.

Tk_PhotoExpand は部品の影像が画素単位の寸法で少なくとも width × height になる様拡張される｡もし使用者が -width and/or -height の構成設定指示項目により明示的に影像の巾と高さを指定する場合､巾と/か 高さは変更されない｡もし影像データが多くの小さい区間に供給された場合､影像区間が供給された様に影像が多くの少ない増加を許容するよりも､最初に Tk_PhotoExpand or Tk_PhotoSetSize を使用する方が効果的である｡ Tk_PhotoExpand requests that the widget's image be expanded to be at least width x height pixels in size. The width and/or height are unchanged if the user has specified an explicit image width or height with the -width and/or -height configuration options, respectively. If the image data are being supplied in many small blocks, it is more efficient to use Tk_PhotoExpand or Tk_PhotoSetSize at the beginning rather than allowing the image to expand in many small increments as image blocks are supplied.

Tk_PhotoExpand は通常 TCL_OK を返すが､結果の影像を保有する充分な記憶域が割当てられない場合､ TCL_ERROR が返され､もし interp 引数が非-NULL の場合不都合伝言文が解釈実行機能の結果に置かれる｡ Tk_PhotoExpand normally returns TCL_OK, though if it cannot allocate sufficient memory to hold the resulting image, TCL_ERROR is returned instead and, if the interp argument is non-NULL, an error message is placed in the interpreter's result.

Tk_PhotoSetSize は､恰も使用者が与えられた width and height 値を -width and -height 構成設定指示項目に指定した如く影像の寸法を指定する｡ width or height に対する零の値は影像の巾や高さを変更しないが､継続する Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock or Tk_PhotoExpand.呼出しにより巾や高さが変更されることを許容する｡ Tk_PhotoSetSize specifies the size of the image, as if the user had specified the given width and height values to the -width and -height configuration options. A value of zero for width or height does not change the image's width or height, but allows the width or height to be changed by subsequent calls to Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock or Tk_PhotoExpand.

Tk_PhotoSetSize は通常 TCL_OK を返すが､結果の影像を保有する充分な記憶域が割当てられない場合､ TCL_ERROR が返され､もし interp 引数が非-NULL の場合不都合伝言文が解釈実行機能の結果に置かれる｡ Tk_PhotoSetSize normally returns TCL_OK, though if it cannot allocate sufficient memory to hold the resulting image, TCL_ERROR is returned instead and, if the interp argument is non-NULL, an error message is placed in the interpreter's result.

Tk_PhotoGetSize returns the dimensions of the image in *widthPtr and *heightPtr.

### 移植性 PORTABILITY

Tk 8.3 以前内では Tk_PhotoPutBlock と Tk_PhotoPutZoomedBlock は､異なる定義を有していた｡もし 8.4 版に対する古い対話機能を使う符号を貴兄の符号命令の更新なしに機械語翻訳したい場合は､ -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK 旗印を設定してそれを機械語翻訳されたい｡古い版の Tk に対する Stubs を使って連結された符号命令は継続して動くであろう｡ In Tk 8.3 and earlier, Tk_PhotoPutBlock and Tk_PhotoPutZoomedBlock 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.

Tk 8.4 版では Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoExpand and Tk_PhotoSetSize は interp 引数を取らず何も結果の符合を返さない｡もし影像に充分の記憶域が利用できない場合､ Tk は混乱する｡もし拡張が追加的旗印 -DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE を伴って機械語翻訳された場合は､この挙動は依然運営されている｡古い版の Tk に対する Stubs を使って連結された符号命令は継続して動くであろう｡ In Tk 8.4, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoExpand and Tk_PhotoSetSize did not take an interp argument or return any result code. If insufficient memory was available for an image, Tk would panic. This behaviour is still supported if you compile your extension with the additional flag -DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE. Code linked using Stubs against older versions of Tk will continue to work.

### 瑕疵 BUGS

Tk_PhotoImageBlock 構造は データの配列に大きな柔軟性(譬ば､赤､緑､青､透明度の面を分ける)を托して映像データを Tk_PhotoPutBlock に提供していた｡不幸な事に実装はその附託に失敗した｡問題点は pixelSize 欄は(間違って)映像が透明度を保有しているか否かの決定に使用されることである｡現在､透明度の為の偏寄が pixelSize と同じかより大きい場合 tk_PhotoPutblock は透明度がないと看做し､映像を完全に不透明にする｡これは､経路が分離されている配列法(或いは､pixelSize が透明度の偏寄より小さいに違いない何か風変わりな配列法)では､透明度の経路は正しく読まれないことを意味する｡将来の改版でこの問題が正された場合､念のため､常に透明度データを提供し - 縦え映像が透明度を保持しない場合も - pixelSize には白黒濃淡画は 2 を､ RGB データは 4 を､偏移には それぞれ 0, 0, 0, 1 と 0, 1, 2, 3 とする"標準的な"配列のみを使用することを強く推奨する｡　　　 The Tk_PhotoImageBlock structure used to provide image data to Tk_PhotoPutBlock promises great flexibility in the layout of the data (e.g. separate planes for the red, green, blue and alpha channels). Unfortunately, the implementation fails to hold this promise. The problem is that the pixelSize field is (incorrectly) used to determine whether the image has an alpha channel. Currently, if the offset for the alpha channel is greater than or equal to pixelSize, tk_PhotoPutblock assumes no alpha data is present and makes the image fully opaque. This means that for layouts where the channels are separate (or any other exotic layout where pixelSize has to be smaller than the alpha offset), the alpha channel will not be read correctly. In order to be on the safe side if this issue will be corrected in a future release, it is strongly recommended you always provide alpha data - even if the image has no transparency - and only use the "standard" layout with a pixelSize of 2 for grayscale and 4 for RGB data with offsets of 0, 0, 0, 1 or 0, 1, 2, 3 respectively.

### 著作権表示 CREDITS

写真影像型のための符号は Paul Mackerras 氏により彼の初期の写真部品符号に基き開発された｡ The code for the photo image type was developed by Paul Mackerras, based on his earlier photo widget code.

### KEYWORDS

photo, image
Copyright © 1994 The Australian National University
Copyright © 1994-1996 Sun Microsystems, Inc.