1.94.3 Send methods

image ->initialise: name=[source_sink]*, width=[int], height=[int], kind=[{bitmap,pixmap}]

Two idiomatic ways to construct an image:

• Reusable file-backed image: new(I, image(File)). The constructor first looks File up in @images; on a hit it returns the existing instance. Otherwise it builds a new image and image->loads its pixels from the file. Such images get image<-access read.
• Anonymous read-write image: new(I, image(@nil, Width, Height)). These images are not pooled and have image<-access both.

  The kind argument selects between pixmap (default) and bitmap.

  See also

  - image->load
  - image<-lookup

image ->unlink:

Release the pixel store and the cairo surface backing the image. Called automatically on destruction.

image ->load: from=[source_sink], path=[char_array]

Load pixels from a file or other source_sink. When the source is a file, it is first located via file->find on path (defaults to image.path).

The decoder is SDL_image, so PNG, JPEG, BMP, GIF, PCX and the other formats supported by SDL_image all load. SVG is recognised by file extension or by sniffing the stream and is rendered through SDL's size-aware SVG loader:

• both image<-width and image<-height non-zero → SVG is rendered at exactly that size;
• both zero → SVG viewport size is used;
• one of the two zero → the other dimension scales to preserve the SVG's aspect ratio.

  Streams that are not SVG fall back to a built-in PNM reader when SDL_image cannot interpret them.

  See also

  pce_image_directory/1

image ->save: in=[file], format=[{png,jpeg,webp,avif,gif,bmp,tga,ico,cur}], quality=[0..100]

Write the image to a file. If format is omitted, the extension of the file selects it (e.g., .jpg or .jpeg for JPEG); an extension that is not one of these formats writes PNG. quality is used by the lossy formats JPEG, WebP and AVIF; the default is 90. JPEG and BMP have no transparency. GIF has 256 colours. Whether WebP and AVIF are available depends on how SDL_image was built (see display<-image_save_formats): if not, image->save fails with a message on the console.

For example:

?- send(Image, save, 'photo.jpg'),
   send(Image, save, 'small.webp', webp, 50).

in defaults to image<-file, the file the image was loaded from. That is a source_sink rather than a file: if it is not something we can write to, image->save fails with a message on the console.

image ->resize: width=int, height=int

Resize the image to the indicated dimensions, preserving the overlapping pixels. Newly-exposed area is cleared to the background. See also image<-scale.

image ->copy: from=image|sdl_texture

Replace the receiver's pixels with an exact copy of the argument. The size of the receiver becomes the size of the argument. The pixels of an sdl_texture are converted to RGB, so this copies, e.g., the current frame of a camera into an existing image. Use image->draw_in to blit an image into a sub-area instead.

image ->draw_in: graphical, at=[point]

Render the given graphical (or image) onto the receiver at the given offset (default point(0,0)).

image ->clear:

Clear the entire image to the background (transparent for pixmap, 0 for bitmap).

image ->fill: colour, [area]

Fill the indicated area (default whole image) with the given colour.

image ->pixel: x=int, y=int, value=colour|bool

Set the pixel at (x, y) to the given colour (for pixmap) or boolean (for bitmap).

image ->has_alpha:

Succeed when the image is not fully opaque (at least one pixel has alpha < 255).