NAME
FindPhoto, PhotoPutBlock, PhotoPutZoomedBlock, PhotoGetImage, PhotoBlank, PhotoExpand, PhotoGetSize, PhotoSetSize - manipulate the image displayed in a photo widget.

SYNOPSIS
#include <tk.h>
#include <tkPhoto.h>

PhotoHandle
FindPhoto(window_path)

void
PhotoPutBlock(handle, block, x, y, width, height)

void
PhotoPutZoomedBlock(handle, block, x, y, width, height,
zoom_x, zoom_y, decimate_x, decimate_y)

int
PhotoGetImage(handle, block)

void
PhotoBlank(handle)

void
PhotoExpand(handle, width, height)

void
PhotoGetSize(handle, widthp, heightp)

void
PhotoSetSize(handle, width, height)

ARGUMENTS
Window pathname of the desired photo widget. Opaque handle to identify the photo widget to be affected. Specifies the address and storage layout of image data. Specifies the X coordinate where the top-left corner of the block is to be placed within the image. Specifies the Y coordinate where the top-left corner of the block is to be placed within the image. Specifies the width of the image area to be affected (for PhotoPutBlock) or the desired image width (for PhotoExpand and PhotoSetSize). Specifies the height of the image area to be affected (for PhotoPutBlock) or the desired image height (for PhotoExpand and PhotoSetSize). Pointer to location in which to store the image width. Pointer to location in which to store the image height. Specifies the decimation factor in the X direction for input image data. Specifies the decimation factor in the Y direction for input image data. Specifies the zoom factor to be applied in the X direction to pixels being written to the photo image. Specifies the zoom factor to be applied in the Y direction to pixels being written to the photo image.

DESCRIPTION

FindPhoto returns an opaque handle which is used to identify a particular photo widget to the other procedures. The parameter is the window path name used when creating the photo widget (using the photo Tcl command). The widget must be created before FindPhoto is called.

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 -imagesize widget configuration option (see photo(1)); in that case the area is silently clipped to the image boundaries.

The block parameter is a pointer to a PhotoImage structure, defined as follows: typedef struct {
    unsigned char *ptr;    /* points to image data */
    int    width;    /* horiz # pixels in block */
    int    height;    /* vert # pixels in block */
    int    pitch;    /* # bytes stored per line */
    int    pixel_size;    /* # bytes per pixel */
    int    comp_off[3];    /* offset to R,G,B components */
} PhotoImage;

The ptr field points to the first pixel (top-left corner). The width and height fields specify the dimensions of the block of pixels. The pixel_size field specifies the address difference between two horizontally adjacent pixels. Normally it is 3 or 4, but it can have any value. The pitch field specifies the address difference between two vertically adjacent pixels. The comp_off array contains the offsets from the address of a pixel to the addresses of the bytes containing the red, green and blue components. These are normally 0, 1 and 2, but can have other values, e.g., for images which are stored as separate red, green and blue images.

The value given for the width and height parameters to PhotoPutBlock do not have to correspond to the values specified in block. If they are smaller, 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.

PhotoPutZoomedBlock works like PhotoPutBlock except that the image can be reduced or enlarged for display. The decimate_x and decimate_y parameters allow the size of the image to be reduced by decimation. PhotoPutZoomedBlock will use only pixels from the input image whose X coordinates are multiples of decimate_x, and whose Y coordinates are multiples of decimate_y. For example, an image of 512x512 pixels can be reduced to 256x256 by setting decimate_x and decimate_y to 2.

The zoom_x and zoom_y parameters allow the image to be enlarged by pixel replication. Each pixel of the (possibly decimated) input image will be written to a block zoom_x pixels wide and zoom_y pixels high of the displayed image. Decimation and zooming can be used together for special effects.

PhotoGetImage can be used to get image data back from a photo widget, but only if given photo is storing image data, that is, if the dither-level (set with the -ditherlevel widget configuration option) of the photo is non-zero. If it is, PhotoGetImage fills in the structure pointed to by the block parameter with values which describe the address and layout of the image data which the widget has stored internally, and returns 1. The values are valid until the widget is destroyed, its image size is changed, its dither-level is changed, or its palette is changed from monochrome to color or vice versa. If the widget does not have image data stored, PhotoGetImage fills in all fields in the structure pointed to by block except for ptr, which is set to NULL, and returns 0.

PhotoBlank clears the entire image stored in the photo widget to the blank color (usually black).

PhotoExpand requests that the widget's image be expanded to be at least width x height pixels in size. This has no effect if the user has specified an explicit image size. If the image data are being supplied in many small blocks, it is more efficient to use PhotoExpand or PhotoSetSize at the beginning rather than allowing the image to expand in many small increments as image blocks are supplied.

PhotoSetSize specifies the size of the image. The size given overrides any previous size. This call is equivalent to specifying the size with the -imagesize widget configuration option. If both width and height are zero, the user-specified size is countermanded, and the image size will be determined as specified in photo(1).

PhotoGetSize returns the dimensions of the widget's image in *widthp and *heightp.

KEYWORDS
photo widget, image