Index

Package: Pixbuf

Description

package Gdk.Pixbuf is

This object provides image manipulation routines.

The following image formats are known, but some depend on external libraries for the proper loading of files (indicated with * in the list): PNG*, JPEG*, TIFF*, GIF, XPM, PNM, Sun raster file (ras), ico, bmp.

With this package, you can load images from file, display them on the screen, re-scale them and compose them with other images.

All the functions fully support alpha channels (opacity).

Different filters are provided, depending on the quality of output you expect and the speed you need.

Binding from C File version 1.3.11

<testgtk>create_pixbuf.adb</testgtk>

Classes

Gdk_Pixbuf_Record

type Gdk_Pixbuf_Record is new Glib.Object.GObject_Record with private;

Ancestors:

Primitive operations:

Glib.Object.Deallocate (Inherited)
Glib.Object.Get_Type (Inherited)
Glib.Object.Notify (Inherited)
Glib.Object.Ref (Inherited)
Glib.Object.Ref_Sink (Inherited)
Glib.Object.Unref (Inherited)

Types

Gdk_Pixbuf

type Gdk_Pixbuf is access all Gdk_Pixbuf_Record'Class;
A very efficient client-side pixmap. This type can be adapted to all the possible screen depths (number of bits per pixel), and the algorithms are extremely efficient. You can also load a pixbuf directly from an external file in one of the standard image formats.

Gdk_Pixbuf_Animation

type Gdk_Pixbuf_Animation is new Glib.C_Proxy;
Type used for animations.

Gdk_Pixbuf_Animation_Iter

type Gdk_Pixbuf_Animation_Iter is new Glib.C_Proxy;
Type used to iterate through an animation.

Alpha_Mode

type Alpha_Mode is (Alpha_Bilevel, Alpha_Full);
Alpha compositing mode. This indicates how the alpha channel (for opacity) is handled when rendering.

Gdk_Colorspace

type Gdk_Colorspace is (Colorspace_RGB);
Type of the image. The only possible value is currently RGB, but extensions will exist with CMYK, Gray, Lab, ...

Gdk_Interp_Type

type Gdk_Interp_Type is
     (Interp_Nearest,
      --  Nearest neighbor. It is the fastest and lowest quality.

      Interp_Tiles,
      --  Accurate simulation of the Postscript image operator
      --  without any interpolation enabled; each pixel is rendered as a tiny
      --  parallelogram of solid color, the edges of which are implemented
      --  with anti-aliasing. It resembles nearest neighbor for enlargement,
      --  and bilinear for reduction.

      Interp_Bilinear,
      --  Bilinear interpolation. For enlargement, it is equivalent to
      --  point-sampling the ideal bilinear-interpolated image. For reduction,
      --  it is equivalent to laying down small tiles and integrating over the
      --  coverage area.

      Interp_Hyper
      --  Filter_Hyper is the highest quality reconstruction function. It is
      --  derived from the hyperbolic filters in Wolberg's "Digital Image
      --  Warping," and is formally defined as the hyperbolic-filter sampling
      --  the ideal hyperbolic-filter interpolated image (the filter is
      --  designed to be idempotent for 1:1 pixel mapping). It is the slowest
      --  and highest quality.
     );

File_Format

type File_Format is (JPEG, PNG, ICO, BMP);
Possible formats when saving a file.

Image_Quality

type Image_Quality is range 0 .. 100;
For a JPEG image only, quality of the image in percentage.

Alpha_Range

type Alpha_Range is range 0 .. 255;
Valid values for alpha parameters.

Gdk_Rgb_Dither

type Gdk_Rgb_Dither is (Dither_None, Dither_Normal, Dither_Max);
The three kinds of dithering that are implemented in this package: - Dither_None: No dithering will be done - Dither_Normal: Specifies dithering on 8 bit displays, but not 16-bit. Usually the best choice. - Dither_Max: Specifies dithering on every kind of display

Rgb_Record

type Rgb_Record is record
      Red, Green, Blue : Glib.Guchar;
   end record;

Unchecked_Rgb_Buffer

type Unchecked_Rgb_Buffer is array (Glib.Guint) of Rgb_Record;

Rgb_Buffer_Access

type Rgb_Buffer_Access is access all Unchecked_Rgb_Buffer;

Constants & Global variables

Null_Pixbuf (Gdk_Pixbuf)

Null_Pixbuf : constant Gdk_Pixbuf := null;

Corrupt_Image

Corrupt_Image         : constant := 0;
image data hosed

Insufficient_Memory

Insufficient_Memory   : constant := 1;
no mem to load image

Bad_Option

Bad_Option            : constant := 2;
bad option passed to save routine

Unknown_Type

Unknown_Type          : constant := 3;
unsupported image type

Unsupported_Operation

Unsupported_Operation : constant := 4;
unsupported operation (load, save) for image type

Failed

Failed                : constant := 5;
Operation failed.

Subprograms & Entries

Get_Type

function Get_Type return Glib.GType;
Return the internal value associated with a Gdk_Pixbuf.

Get_Colorspace

function Get_Colorspace 
(Pixbuf: Gdk_Pixbuf) return Gdk_Colorspace;
Query the color space of a pixbuf.

Get_N_Channels

function Get_N_Channels 
(Pixbuf: Gdk_Pixbuf) return Gint;
Number of channels in the image.

Get_Has_Alpha

function Get_Has_Alpha 
(Pixbuf: Gdk_Pixbuf) return Boolean;
Return True if the image has an alpha channel (opacity information).

Get_Bits_Per_Sample

function Get_Bits_Per_Sample 
(Pixbuf: Gdk_Pixbuf) return Gint;
Number of bits per color sample.

Get_Pixels

function Get_Pixels 
(Pixbuf: Gdk_Pixbuf) return Rgb_Buffer_Access;
Return a pointer to the pixel data of the image.

Get_Width

function Get_Width 
(Pixbuf: Gdk_Pixbuf) return Gint;
Return the width of the image in pixels.

Get_Height

function Get_Height 
(Pixbuf: Gdk_Pixbuf) return Gint;
Return the height of the image in pixels.

Get_Rowstride

function Get_Rowstride 
(Pixbuf: Gdk_Pixbuf) return Gint;
Return the number of bytes between rows in the image data.

Gdk_New

function Gdk_New 
(Colorspace: Gdk_Colorspace := Colorspace_RGB;
Has_Alpha: Boolean := False;
Bits_Per_Sample: Gint := 8;
Width: Gint;
Height: Gint) return Gdk_Pixbuf;
Create a blank pixbuf with an optimal row stride and a new buffer. The buffer is allocated, but not cleared. The reference counting is initialized to 1.

Copy

function Copy 
(Pixbuf: Gdk_Pixbuf) return Gdk_Pixbuf;
Copy a pixbuf.

Gdk_New_Subpixbuf

function Gdk_New_Subpixbuf 
(Src_Pixbuf: Gdk_Pixbuf;
Src_X: Gint;
Src_Y: Gint;
Width: Gint;
Height: Gint) return Gdk_Pixbuf;
Create a pixbuf which points to the pixels of another pixbuf

Gdk_New_From_File

procedure Gdk_New_From_File 
(Pixbuf: out Gdk_Pixbuf;
Filename: String;
Error: out GError);
Load an image from file.

Gdk_New_From_Data

function Gdk_New_From_Data 
(Data: Guchar_Array_Access;
Colorspace: Gdk_Colorspace := Colorspace_RGB;
Has_Alpha: Boolean := False;
Bits_Per_Sample: Gint := 8;
Width: Gint;
Height: Gint;
Rowstride: Gint;
Auto_Destroy_Data: Boolean := True) return Gdk_Pixbuf;
Create a pixbuf out of in-memory image data. Currently only RGB images with 8 bits per sample are supported. Width and Height must be > 0. Rowstride is the distance in bytes between row starts. A typical value is 4*Width when there is an Alpha channel. If Auto_Destroy_Data is true, passed data will be automatically freed when the reference count of the pixbuf reaches 1. Otherwise, data is never freed.

Gdk_New_From_Xpm_Data

function Gdk_New_From_Xpm_Data 
(Data: Interfaces.C.Strings.chars_ptr_array) return Gdk_Pixbuf;
Create an image from a XPM data.

Fill

procedure Fill 
(Pixbuf: Gdk_Pixbuf;
Pixel: Guint32);
Fill pixbuf with a given pixel value.

Save

procedure Save 
(Pixbuf: Gdk_Pixbuf;
Filename: String;
Format: File_Format;
Error: out GError;
Quality: Image_Quality := Image_Quality'Last;
Depth: Integer := 32);
Save pixbuf to a file. Quality is only taken into account for JPEG images. Depth is only taken into account for ICO images and can take the values 16, 24 or 32. Error is set to null on success, and set to a GError otherwise.

Add_Alpha

function Add_Alpha 
(Pixbuf: Gdk_Pixbuf;
Substitute_Color: Boolean := False;
Red: Guchar := 0;
Green: Guchar := 0;
Blue: Guchar := 0) return Gdk_Pixbuf;
Add an alpha channel. Return a newly allocated image copied from Pixbuf, but with an extra alpha channel. If Pixbuf already had an alpha channel, the two images have exactly the same contents. If Substitute_Color is True, the color (Red, Green, Blue) is substituted for zero opacity. If Substitute_Color is False, Red, Green and Blue are ignored, and a new color is created with zero opacity.

Copy_Area

procedure Copy_Area 
(Src_Pixbuf: Gdk_Pixbuf;
Src_X: Gint;
Src_Y: Gint;
Width: Gint;
Height: Gint;
Dest_Pixbuf: Gdk_Pixbuf;
Dest_X: Gint;
Dest_Y: Gint);
Copy a rectangular area from Src_pixbuf to Dest_pixbuf. Conversion of pixbuf formats is done automatically.

Saturate_And_Pixelate

procedure Saturate_And_Pixelate 
(Src: Gdk_Pixbuf;
Dest: Gdk_Pixbuf;
Saturation: Gfloat;
Pixelate: Boolean := True);
Brighten/darken and optionally make it pixelated-looking.

Get_From_Window

function Get_From_Window 
(Window: Gdk_Window;
Src_X: Gint;
Src_Y: Gint;
Width: Gint;
Height: Gint) return Gdk_Pixbuf;

Get_From_Surface

function Get_From_Surface 
(Surface: Cairo.Cairo_Surface;
Src_X: Gint;
Src_Y: Gint;
Width: Gint;
Height: Gint) return Gdk_Pixbuf;
Transfers image data from a Gdk_Window and converts it to an RGB(A) representation inside a Gdk_Pixbuf. In other words, copies image data from a server-side drawable to a client-side RGB(A) buffer. This allows you to efficiently read individual pixels on the client side. This function will create an RGB pixbuf with 8 bits per channel with the same size specified by the Width and Height arguments. The pixbuf will contain an alpha channel if the window contains one. If the window is off the screen, then there is no image data in the obscured/offscreen regions to be placed in the pixbuf. The contents of portions of the pixbuf corresponding to the offscreen region are undefined. If the window you're obtaining data from is partially obscured by other windows, then the contents of the pixbuf areas corresponding to the obscured regions are undefined. If the window is not mapped (typically because it's iconified/minimized or not on the current workspace), then Null_Pixbuf will be returned. If memory can't be allocated for the return value, Null_Pixbuf will be returned instead. (In short, there are several ways this function can fail, and if it fails it returns Null_Pixbuf; so check the return value.) Return value: (transfer full): A newly-created pixbuf with a reference count of 1, or Null_Pixbuf on error

Scale

procedure Scale 
(Src: Gdk_Pixbuf;
Dest: Gdk_Pixbuf;
Dest_X: Gint;
Dest_Y: Gint;
Dest_Width: Gint;
Dest_Height: Gint;
Offset_X: Gdouble := 0.0;
Offset_Y: Gdouble := 0.0;
Scale_X: Gdouble := 1.0;
Scale_Y: Gdouble := 1.0;
Inter_Type: Gdk_Interp_Type := Interp_Bilinear);
Transform the source image by scaling by Scale_x and Scale_y then translating by Offset_x and Offset_y. The image is then rendered in the rectangle (Dest_x, Dest_y, Dest_width, Dest_height) of the resulting image onto the destination drawable replacing the previous contents.

Composite

procedure Composite 
(Src: Gdk_Pixbuf;
Dest: Gdk_Pixbuf;
Dest_X: Gint;
Dest_Y: Gint;
Dest_Width: Gint;
Dest_Height: Gint;
Offset_X: Gdouble := 0.0;
Offset_Y: Gdouble := 0.0;
Scale_X: Gdouble := 1.0;
Scale_Y: Gdouble := 1.0;
Inter_Type: Gdk_Interp_Type := Interp_Bilinear;
Overall_Alpha: Alpha_Range := 128);
Transform the source image by scaling by Scale_X and Scale_Y then translating by Offset_X and Offset_Y, then composite the rectangle (Dest_X, Dest_Y, Dest_Width, Dest_Height) of the resulting image onto the destination drawable.

Composite_Color

procedure Composite_Color 
(Src: Gdk_Pixbuf;
Dest: Gdk_Pixbuf;
Dest_X: Gint;
Dest_Y: Gint;
Dest_Width: Gint;
Dest_Height: Gint;
Offset_X: Gdouble := 0.0;
Offset_Y: Gdouble := 0.0;
Scale_X: Gdouble := 1.0;
Scale_Y: Gdouble := 1.0;
Inter_Type: Gdk_Interp_Type := Interp_Bilinear;
Overall_Alpha: Alpha_Range := 128;
Check_X: Gint := 0;
Check_Y: Gint := 0;
Check_Size: Gint := 0;
Color1: Guint32 := 0;
Color2: Guint32 := 0);
Transform the source image by scaling by Scale_x and Scale_y then translating by Offset_x and Offset_y, then composites the rectangle (Dest_X, Dest_Y, Dest_Width, Dest_Height) of the resulting image with a checkboard of the colors Color1 and Color2 and renders it onto the destination drawable. The origin of checkboard is at (Check_x, Check_y) Color1 is the color at the upper left of the check.

Scale_Simple

function Scale_Simple 
(Src: Gdk_Pixbuf;
Dest_Width: Gint;
Dest_Height: Gint;
Inter_Type: Gdk_Interp_Type := Interp_Bilinear) return Gdk_Pixbuf;
Scale the Src image to Dest_width x Dest_height and render the result into a new pixbuf.

Composite_Color_Simple

function Composite_Color_Simple 
(Src: Gdk_Pixbuf;
Dest_Width: Gint;
Dest_Height: Gint;
Inter_Type: Gdk_Interp_Type := Interp_Bilinear;
Overall_Alpha: Alpha_Range := 128;
Color1: Guint32 := 0;
Color2: Guint32 := 0) return Gdk_Pixbuf;
Scale Src to Dest_width x Dest_height and composite the result with a checkboard of colors Color1 and Color2 and render the result into a new pixbuf.

Get_Type_Animation

function Get_Type_Animation return Glib.GType;
Return the internal value associated with a Gdk_Pixbuf_Animation.

Gdk_New_From_File

procedure Gdk_New_From_File 
(Animation: out Gdk_Pixbuf_Animation;
Filename: String;
Error: out GError);
Create a new animation by loading it from a file. The file format is detected automatically. If the file's format does not support multi-frame images, then an animation with a single frame will be created. Possible errors are in the Pixbuf_Error and GFile_Error domains. On return, Animation is a newly created animation with a reference count of 1, or null if any of several error conditions ocurred: the file could not be opened, there was no loader for the file's format, there was not enough memory to allocate the image buffer, or the image file contained invalid data.

Ref

procedure Ref 
(Animation: Gdk_Pixbuf_Animation);
Increment the reference counting on the animation.

Unref

procedure Unref 
(Animation: Gdk_Pixbuf_Animation);
Decrement the reference counting on the animation.

Get_Width

function Get_Width 
(Animation: Gdk_Pixbuf_Animation) return Gint;
Return the width of the bounding box of a pixbuf animation.

Get_Height

function Get_Height 
(Animation: Gdk_Pixbuf_Animation) return Gint;
Return the height of the bounding box of a pixbuf animation.

Is_Static_Image

function Is_Static_Image 
(Animation: Gdk_Pixbuf_Animation) return Boolean;
If you load a file with Gdk_New_From_File and it turns out to be a plain, unanimated image, then this function will return True. Use Get_Static_Image to retrieve the image.

Get_Static_Image

function Get_Static_Image 
(Animation: Gdk_Pixbuf_Animation) return Gdk_Pixbuf;
If an animation is really just a plain image (has only one frame), this function returns that image. If the animation is an animation, this function returns a reasonable thing to display as a static unanimated image, which might be the first frame, or something more sophisticated. If an animation hasn't loaded any frames yet, this function will return null.

Get_Iter

function Get_Iter 
(Animation: Gdk_Pixbuf_Animation;
Start_Time: GTime_Val_Access := null) return Gdk_Pixbuf_Animation_Iter;
Get an iterator for displaying an animation. The iterator provides the frames that should be displayed at a given time. It should be freed after use with Unref. Start_Time would normally come from G_Get_Current_Time, and marks the beginning of animation playback. After creating an iterator, you should immediately display the pixbuf returned by Get_Pixbuf. Then, you should install a timeout (with Timeout_Add) or by some other mechanism to ensure that you'll update the image after Get_Delay_Time milliseconds. Each time the image is updated, you should reinstall the timeout with the new, possibly-changed delay time. As a shortcut, if Start_Time is equal to null, the result of G_Get_Current_Time will be used automatically. To update the image (i.e. possibly change the result of Get_Pixbuf to a new frame of the animation), call Advance. If you're using Gdk_Pixbuf_Loader, in addition to updating the image after the delay time, you should also update it whenever you receive the area_updated signal and On_Currently_Loading_Frame returns True. In this case, the frame currently being fed into the loader has received new data, so needs to be refreshed. The delay time for a frame may also be modified after an area_updated signal, for example if the delay time for a frame is encoded in the data after the frame itself. So your timeout should be reinstalled after any area_updated signal. A delay time of -1 is possible, indicating "infinite."

Get_Type_Animation_Iter

function Get_Type_Animation_Iter return Glib.GType;
Return the internal value associated with a Gdk_Pixbuf_Animation_Iter.

Ref

procedure Ref 
(Iter: Gdk_Pixbuf_Animation_Iter);
Increment the reference counting on the iterator.

Unref

procedure Unref 
(Iter: Gdk_Pixbuf_Animation_Iter);
Decrement the reference counting on the iterator.

Get_Delay_Time

function Get_Delay_Time 
(Iter: Gdk_Pixbuf_Animation_Iter) return Gint;
Return the number of milliseconds the current pixbuf should be displayed or -1 if the current pixbuf should be displayed forever. Timeout_Add conveniently takes a timeout in milliseconds, so you can use a timeout to schedule the next update.

Get_Pixbuf

function Get_Pixbuf 
(Iter: Gdk_Pixbuf_Animation_Iter) return Gdk_Pixbuf;
Return the current pixbuf which should be displayed. The pixbuf will be the same size as the animation itself (Get_Width, Get_Height). This pixbuf should be displayed for Get_Delay_Time milliseconds. The caller of this function does not own a reference to the returned pixbuf; the returned pixbuf will become invalid when the iterator advances to the next frame, which may happen anytime you call Advance. Copy the pixbuf to keep it (don't just add a reference), as it may get recycled as you advance the iterator.

On_Currently_Loading_Frame

function On_Currently_Loading_Frame 
(Iter: Gdk_Pixbuf_Animation_Iter) return Boolean;
Used to determine how to respond to the area_updated signal on Gdk_Pixbuf_Loader when loading an animation. area_updated is emitted for an area of the frame currently streaming in to the loader. So if you're on the currently loading frame, you need to redraw the screen for the updated area.

Advance

function Advance 
(Iter: Gdk_Pixbuf_Animation_Iter;
Current_Timer: GTime_Val_Access := null) return Boolean;
Possibly advance an animation to a new frame. Chooses the frame based on the start time passed to Get_Iter. Current_Time would normally come from G_Get_Current_Time, and must be greater than or equal to the time passed to Get_Iter, and must increase or remain unchanged each time Get_Pixbuf is called. That is, you can't go backward in time; animations only play forward. As a shortcut, pass null for the current time and G_Get_Current_Time will be invoked on your behalf. So you only need to explicitly pass Current_Time if you're doing something odd like playing the animation at double speed. If this function returns False, there's no need to update the animation display, assuming the display had been rendered prior to advancing; if True, you need to call Get_Pixbuf and update the display with the new pixbuf.

Gdk_New_From_Pixbuf

procedure Gdk_New_From_Pixbuf 
(Cursor: out Gdk.Gdk_Cursor;
Display: Gdk.Display.Gdk_Display := Gdk.Display.Get_Default;
Pixbuf: Gdk_Pixbuf;
X: Glib.Gint;
Y: Glib.Gint);
Create a cursor from a pixbuf. Not all GDK backends support RGBA cursors. If they are not supported, a monochrome approximation will be displayed. The functions gdk.display.supports_cursor_alpha and gdk.display.supports_cursor_color can be used to determine whether RGBA cursors are supported; gdk.display.get_default_cursor_size and gdk.display.get_maximal_cursor_size give information about cursor sizes. On the X backend, support for RGBA cursors requires a sufficently new version of the X Render extension.

Get_Image

function Get_Image 
(Cursor: Gdk.Gdk_Cursor) return Gdk_Pixbuf;
Return the image stored in the cursor

Convert

function Convert 
(P: System.Address) return Gdk_Pixbuf;
<doc_ignore>