PCE version 4C man_modulenamespaceid_tablemodified current_idOIxN class/imageN referenceC hash_tablerefersizeOIxNbothIsNV.image.backgroundCman_variable_card identifiermodule last_modifiednamesummary descriptionsee_alsoinheritdefaultsOIxNV.image.backgroundRICdateOIx)3IN backgroundnCstringOIx8Colour used to clear area's for images of <-kind pixmap.nnnsNC.imageCman_class_card identifiermodule last_modifiednamesummary descriptionsee_alsoinherituser_interfacebugsOIxNC.imageRIOIx0G)NimagenOIxAn image is a two-dimensional array of pixels. Images are used for various purposes: * fill-patterns for graphicals * `Image' for frame-icons, cursors and other X-objects * `Image' for PCE bitmap objects * `Image' for various PCE objects: markers in menu's, etc. * Scratch area's to for background graphical operations. The most common usages for application programmers are fill-patterns and bitmaps to be used as icons. In both forms, the pixels of the image are normally never changed and the image may thus be reused. For this reason, images are normally created from a file argument. They are created as read-only images (see `Image <->access'). See `Image ->initialise' for details.CchainsizeOI xIeN$class/bitmap$C.bitmapeNM.image.S.initialiseEN V.image.kindXnnnsN M.image.S.andCman_method_card identifiermodule last_modifiednamesummary descriptionsee_alsoinherit diagnosticsdefaultsbugsOI xN M.image.S.andRIOI x)8NandnOI x>Edit operation: bitwise and operation with the argument image.nnOI x#no_access: Image has access `read'.nnsNV.image.foregroundOIxNV.image.foregroundRIOIx)4fN foregroundnOIxFDefault colour used for drawing graphicals on images of <-kind pixmap.nnnsNM.image.S.loadOIxNM.image.S.loadRIOIx<,R6NloadnOIxLoad the image from the named file or <-file. First, the file is located using `file ->find' in either `path' or image.path. If successful, the image is loaded. This method automatically recognises the following formats: * Standard X11 bitmap (XBM) and pixmap (XPM) formats * PNM (Portable Any Map) * Windows .BMP, .ICO and .CRS formats (Windows version only). * JPEG and GIF for compressed real-life images. When loading an XPM (colour) image, the <-hot_spot and <-mask attributes are filled automatically. XPM is the recommended format for colour icons that are to be used with XPCE. XPM files may be created using the X11 pixmap utility. On Windows systems, icons and cursors may be used in the native .ICO or .CRS formats. If portability to the Unix version is required, the images should be loaded in XPCE and saved as .XPM files using ->save. JPEG images support the JPEG_COM marker for storing one or more comment extensions with the image. If such markers are found while loading the image an <-attribute named `comment' is attached to the image object holding a chain object with a string object for each comment encountered. See also ->save. See also pce_image_directory/1.OIxIeN$errors$!.bad_fileENM.image.S.initialiseXnnnnsNM.image.S.invert_pixelOIxNM.image.S.invert_pixelRIOIx,{,N invert_pixelnOIx^Invert the pixel at X,Y. Note that this operation is ill defined for images with <-depth > 1.nnnnnsNM.image.S._xcloseOIxNM.image.S._xcloseRIOIx5}PN_xclosenOIxXCalled internally to destroy the associated Window System resources. See also ->_xopen.nnnnnsNM.image.S.saveOIxNM.image.S.saveRIOIx<,RNsavenOIx Saves the data of the image for later use or use by external applications. The format argument describes the format in which the data is written: # xbm (default) The X11 bitmap format. All versions of XPCE can read this format, only the X11 implementation can write them as yet. The xbm format can only represent <-kind bitmap (monochrome) images. # xpm The X11 pixmap format. All versions can both read and write this format. # pnm (Portable aNy Map) Selects either or pbm, pgm or ppm, depending on the characteristic of the image. <-kind: bitmap are stored as pbm. <-kind: pixmap is stored as pgm if for all pixels, the red, green and blue values are equal and as ppm otherwise. # pbm (Portable BitMap) Rawbit version of this format. pbm files can only represent <-kind: bitmap (monochrome) images. # pgm (Portable GreyMap) Represents the data as a two-dimensional intensity map. # ppm (Portable PixMap) Represents the data as a two-dimensional map of RGB triples. # jpeg All versions can both read and write JPEG images. JPEG images are written with the jpeg library default options. The JPEG format is an open standard especially suitable for compressing real-life (photo) images. Unlike the other formats, JPEG is *not* lossless. This implies the results generally looks good to the human eye, but is *not* exactly equivalent to the source. If the image implements the <-comment method and this method returns either a char_array object or a chain object holding char_array objects, ->save writes JPEG_COM markers to represent these comments. See also ->load. # gif All versions can both read and write GIF images. GIF is a closed format based on the Lempel-Ziv encoding. The algorithm is loss-less, but the compression on real-life images is far worse than JPEG. The rights around GIF are *extremely vague*. Unisys holds a patent on the Lempel-Ziv encoding. XPCE's routines use a public domain implementation of the algorithm. The patent will expire in 2003. Unisys currently enforces its patent for `highly commercial sites' (i.e. it enforces the patent on distributors of GIF images rather than distributors of implementations of the encoding algorithm). Though we believe we won't be troubled by Unisys, and neither will our academic customers or small-scale commercial users we will remove GIF support from XPCE if we are forced by Unisys. USING XPCE-PRODUCED GIF IMAGES IS AT YOUR OWN RISK. In the long run, we will propably replace the GIF by PNG, which is not troubled by legal issues. Unfortunately the PNG reference implementation library is much too bulky. Some first steps towards small routines doing simple read/write of PNG images appear to be underway. As `in' is a source_sink object, image data can be written to a text_buffer object which can then be manipulated. For example. the library httpd.pl defines an HTTP deamon skeleton using this feature to serve XPCE images as JPEG image data without using an intermediate file. Currently this feature is only available for the p?m, jpeg and gif formats because the libraries for the other formats require a file argument. The PNM/PBM/PGM/PPM format is the central format of a set of public tools for the transformation of images. This toolkit is known as pbmplus. The sources for this toolkit are available from: ftp://swi.psy.uva.nl/pub/xpce/util/pbmplus10dec91.tar.gz ftp://swi.psy.uva.nl/pub/xpce/util/netpbm-1mar1994.tar.gz There are many copies of this toolkit on anonymous ftp sites.nnnnnsN V.image.sizeOIxN V.image.sizeRIOIx)8NsizenOI x=Size of the two-dimensional array of pixels (in pixel-units).nnOI!xThe size of the image specified in the loaded file when the image is loaded from a file. 16x16 pixels if the image is not loaded from a file.sN V.image.nameOI"xN V.image.nameRIOI#x)6NnamenOI$xbName of the image. Used for the lookup of reusable images. See @images and `Image ->initialise'.OI%xIeN $objects$22ENM.image.S.initialiseXnnsNM.image.S.initialiseOI&xNM.image.S.initialiseRIOI'x)2N initialisenOI(xThere are two common forms to create an image: # Read-only images from a file These are created using new(I, image(Name)). In this form, the initialise method does a lookup on the table of reusable images @images. If `Name' is found there, the reusable image is returned. Otherwise a new image is created and it is loaded with the named file (see `Image ->load'). # Read-write images Normally created as new(I, image(@nil, Width, Height)). These images are not reused.OI)xIeN V.image.nameeNM.image.S.loadeN $objects$22ENC.imageXnnnnsN V.image.maskOI*xN V.image.maskRIOI+x2?NmasknOI,xImage for masked painting. The argument image must be ot <-kind: bitmap. Paint will be applied on all places where the mask image has pixels @on. All other places are left untouched. Note that, for monochrome bitmaps (kind: bitmap), `bitmap ->transparent' does the same as making the image a mask of itself. When loading XPM files that have an associated shape extension, (expressed as pixels of colour `None'), the shape image will be associated with the loaded image as the <-mask. See also ->load.nnnsN V.image.kindOI-xN V.image.kindRIOI.x)5NkindnOI/x`Image <-kind' determines the meaning of a pixel-value: # bitmap A pixel value is either @on or @off. When displayed as a graphical object, @on pixels are painted in the colour of the graphical and @off pixels in the background colour. # pixmap A pixel value is a colour. When displayed as a graphical object, these are the true colour used. Within some limits dictated by the colour organisation of the hardware, each pixel may have a different colour. Coloured bitmaps cannot yet be saved to file or loaded from file. PCE encourages the use of ->kind bitmap as this format may be interchanged between various different screen types.OI0xIeN$objects$O.offENC.imageXnOI1xThe default kind is bitmap.sNV.image.displayOI2xNV.image.displayRIOI3x)4NdisplaynOI4xDisplay on which the image is located. This value is @nil for reusable images. Read-write images can only exist on one display.nnnsNV.image.accessOI5xNV.image.accessRIOI6x)3NaccessnOI7xEither `read' or `both'. The first is used for reusable images loaded from a file. The latter is used for read-write images. In this case the image may be associated with only one bitmap. Changes to the image are forwarded to the bitmap.OI8xIENV.image.bitmapXnnsNV.image.hot_spotOI9xNV.image.hot_spotRIOI:x2Nhot_spotnOI;xpHot-spot position. Its value may be set manually, or loaded from a file in XPM format. See ->load for details.nnnsNV.image.bitmapOIxBitmap associated with the image. Only used when <-access equals both. Only one bitmap may be associated with an image that have access both.OI?xIeN$class/bitmap$M.bitmap.S.imageENV.image.accessXnnsN V.image.fileOI@xN V.image.fileRIOIAx)4draw_in to include pixels from another image into this image.nnnnnsNM.image.G.monochromeOIVxNM.image.G.monochromeRIOIWx=PwN monochromenOIXxOCreate a monochrome (black/white) version of pixmap image object. This is achieved by creating an image that has the same dimensions as the original with <-kind: bitmap and draw the original in the monochrome image. The result is implementation-dependent. In general darker areas will map to black (@on) and lighter to white (@off).nnnnnsNM.image.G.scaleOIYxNM.image.G.scaleRIOIZx2LNscalenOI[xCreates a copy of the receiver scaled to the specified dimensions. The Win32 version uses the Windows API function StretchBlt(), while the X11 version uses a very simple algorithm based on the zoom code of xloadimage written by Jim Frost. Notably the X11 version should be regarded as a `Quick and Dirty' solution. If quality scaling is required, use an external image-manipulation package, for example, `xv', (shareware for X11) or the netpbm package distributed as freeware for X11. The latter consist of a number of simple Unix filters, that can easily be called from XPCE/Prolog. The specification of the scaling is in terms of the size of the destination rectangle rather then a factor to avoid rounding problems. To magnify a bitmap by a factor use: magnify(Im, Factor, Magnified) :- get(Im, size, size(W, H)), NW is round(W * Factor), NH is round(H * Factor), get(Im, scale, size(NW, NH), Magnified). See also ->resize and ->rotate.nnnnnXaCnumber O I\xx