From f57c89c21dc40ef9f60b03315d528035570e1de6 Mon Sep 17 00:00:00 2001 From: Miguel de Icaza Date: Tue, 18 Feb 2003 01:33:14 +0000 Subject: [PATCH] Add Pixbuf documentation, 70% done svn path=/trunk/gtk-sharp/; revision=11662 --- doc/en/Gdk/Pixbuf.xml | 895 ++++++++++++++++++++++++++++++++---------- 1 file changed, 686 insertions(+), 209 deletions(-) diff --git a/doc/en/Gdk/Pixbuf.xml b/doc/en/Gdk/Pixbuf.xml index c2b776d9a..cd4d18a0a 100644 --- a/doc/en/Gdk/Pixbuf.xml +++ b/doc/en/Gdk/Pixbuf.xml @@ -1,14 +1,20 @@ - + gdk-sharp 0.0.0.0 - To be added + Not thread safe - To be added - To be added + Represents an image in memory + + + The Gdk.Pixbuf class is used to represent an image in + memory. The in-memory representation uses either a three + byte RGB representation or a four byte RGBA representation. + + GLib.Object @@ -47,11 +53,17 @@ - To be added - To be added: an object of type 'Gdk.Pixdata' - To be added: an object of type 'bool' - To be added: an object of type 'Gdk.Pixbuf' - To be added + + Creates a Pixbuf from a Pixdata + + Source Gdk.Pixdata + Whether to make a private copy of the data + + + The return value is an initialized Pixbuf class + + + @@ -62,9 +74,20 @@ - To be added - To be added: an object of type 'uint' - To be added + + Glib Type ID for the PixbufError interface. + + + + This returns the internal GLib type ID for the PixbufError + interface + + + + + Internal, to be used only with interop with Gtk+ code. + + @@ -75,13 +98,25 @@ - To be added - To be added: an object of type 'uint' - To be added + + Glib Type ID for the AlphaMode interface + + + + This returns the internal GLib type ID for the AlphaMode + interface + + + + + Internal, to be used only with interop with Gtk+ code. + + - + Method Gdk.Pixbuf @@ -90,10 +125,23 @@ - To be added - To be added: an object of type 'string' - To be added: an object of type 'Gdk.Pixbuf' - To be added + + Creates a Pixbuf from an XPM image. + + The string containing the XPM image + + + An initialized Pixbuf class from the XPM image. + + + + + XPM files are typically used in C programs to embed images + in a textual form. They are not typically used with Mono + programs and Gtk# programs as they can embed images + directly using /resource:file.png. + + @@ -109,13 +157,34 @@ - To be added - To be added: an object of type 'bool' - To be added: an object of type 'byte' - To be added: an object of type 'byte' - To be added: an object of type 'byte' - To be added: an object of type 'Gdk.Pixbuf' - To be added + Adds an alpha channel to the Pixbuf + Whether to set a color to zero + opacity. If this is , then the (r, g, b) arguments will be ignored. + Red value to substitute + Green value to substitute + Blue value to substitute + A new pixbuf with an alpha channel. + + + Takes an existing pixbuf and adds an alpha channel to + it. If the existing pixbuf already had an alpha channel, + the channel values are copied from the original; + otherwise, the alpha channel is initialized to 255 (full + opacity). + + + If is , then the color specified by (, , ) + will be assigned zero opacity. That is, if you pass (255, + 255, 255) for the substitute color, all white pixels will + become fully transparent. + + + The original image is not modified, a copy of the image is + made and returned. + + @@ -134,16 +203,31 @@ - To be added - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'Gdk.InterpType' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'uint' - To be added: an object of type 'uint' - To be added: an object of type 'Gdk.Pixbuf' - To be added + Scaling with checkboard rendering + The width of destination image + The height of destination image + The interpolation type for the transformation. + Overall alpha for source image (0..255) + The size of checks in the checkboard (must be a power of two) + The color of check at upper left + The color of the other check + + + The new Pixbuf, or if not enough + memory could be allocated for it. + + + + + Creates a new Pixbuf by scaling to + x + and compositing the result with a checkboard + of colors and . + + + The colors must be in RGB format. + + @@ -158,12 +242,38 @@ - To be added - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'Gdk.InterpType' - To be added: an object of type 'Gdk.Pixbuf' - To be added + Scales a Pixbuf + The width of destination image + The height of destination image + The interpolation type for the transformation + + + A new Pixbuf object, or if no + memory is available for the transformation. + + + + + Create a new GdkPixbuf containing a copy of src scaled to + x . It leaves the current Pixbuf + unaffected. should be if you want maximum + speed (but when scaling down is usually unusably + ugly). The default should + be which offers + reasonable quality and speed. + + + You can scale a sub-portion of the Pixbuf by creating a + sub-pixbuf using a Pixbuf constructor. + + + For more complicated scale/compositions see and + + @@ -191,24 +301,37 @@ - To be added - To be added: an object of type 'Gdk.Pixbuf' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'double' - To be added: an object of type 'double' - To be added: an object of type 'double' - To be added: an object of type 'double' - To be added: an object of type 'Gdk.InterpType' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'uint' - To be added: an object of type 'uint' - To be added + Scale and Compose a Pixbuf with control over the checks + The destination Pixbuf to render to. + The left coordinate for region to render + The top coordinate for region to render + The width of the region to render + The height of the region to render + The offset in the X direction (currently rounded to an integer) + The offset in the Y direction (currently rounded to an integer) + The scale factor in the X direction + The scale factor in the Y direction + The interpolation type for the transformation. + Overall alpha for source image (0..255) + The X offset for the checkboard (origin of checkboard is at -check_x, -check_y) + The Y offset for the checkboard + The size of checks in the checkboard (must be a power of two) + The color of check at upper left + The color of the other check + + + Creates a transformation of the Pixbuf by scaling by + and + then translating by and + , then composites the rectangle + ( ,, + , ) of the resulting image with a + checkboard of the colors and + and renders it onto the + destination imag e. + + @@ -228,17 +351,109 @@ - To be added - To be added: an object of type 'Gdk.Image' - To be added: an object of type 'Gdk.Colormap' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'Gdk.Pixbuf' - To be added + Gets an image from a Gdk.Image + Source Image (A ) + A colormap (if src does not have one set) (A + Source X coordinate within drawable. + Source Y coordinate within drawable. + Destination X coordinate in pixbuf, or 0 + if dest is . + Destination Y coordinate in pixbuf, or 0 + if dest is . + Width in pixels of region to get. + Height in pixels of region to get. + + + + The value of the Pixbuf (the same one that was passed) or + on error. See the remarks below + for details on the possible ways on which this function + might fail. + + + + + Transfers image data from a and + converts it to an RGB(A) representation inside a . In other words, copies image data + from the Image (which might be potentially shared using + shared memory between the client and the server) to a + client-side RGB(A) buffer (the Pixbuf). This allows you to + efficiently read individual pixels on the client side. + + + If the has no colormap ( returns ), then a suitable colormap must be + specified. Typically a or a + pixmap created by passing a to + the constructor will already + have a colormap associated with it. If the has a colormap, the argument will be ignored. If the is a bitmap (1 bit per pixel pixmap), + then a colormap is not required; pixels with a value of 1 + are assumed to be white, and pixels with a value of 0 are + assumed to be black. For taking screenshots, the property returns the + correct colormap to use. + + + + If the specified destination pixbuf is , then this + function will create an RGB Pixbuf with 8 bits per channel + and no alpha, with the same size specified by the width + and height arguments. In this case, the and arguments + must be specified as 0. If the specified destination + pixbuf is not and it contains alpha + information, then the filled pixels will be set to full + opacity (alpha = 255). + + + + If the specified is a pixmap, + then the requested source rectangle must be completely + contained within the pixmap, otherwise the function will + return . For pixmaps only (not for + windows) passing -1 for or + is allowed, to mean the full + width or height of the pixmap. + + + + If the specified is a window, + and 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 corresponding to the offscreen + region are undefined. + + + + If the window you are 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 target image is not mapped (typically because + it's iconified/minimized or not on the current workspace), + then will be returned. + + + + If memory can't be allocated for the return value, will be returned instead. + + + + (In short, there are several ways this function can fail, + and if it fails it returns ; so + check the return value.) + + @@ -261,19 +476,40 @@ - To be added - To be added: an object of type 'Gdk.Drawable' - To be added: an object of type 'Gdk.GC' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'Gdk.RgbDither' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added + Renders the image into a Drawable + Destination drawable. + GC used for rendering. + Source X coordinate within pixbuf. + Source Y coordinate within pixbuf. + Destination X coordinate within drawable. + Destination Y coordinate within drawable. + Width of region to render, in pixels, or -1 to use pixbuf width + Height of region to render, in pixels, or -1 to use pixbuf height + Dithering mode for GdkRGB. + X offset for dither. + Y offset for dither. + + + Renders a rectangular portion of the Pixbuf into the + while using the specified + . This is done using GdkRGB, so the + specified drawable must have the + visual and colormap. Note that this function will ignore + the opacity information for images with an alpha channel; + the GC must already have the clipping mask set if you want + transparent regions to show through. + + + For an explanation of dither offsets, see the GdkRGB + documentation. In brief, the dither offset is important + when re-rendering partial regions of an image to a + rendered version of the full image, or for when the + offsets to a base position change, as in scrolling. The + dither matrix has to be shifted for consistent visual + results. If you do not have any of these cases, the dither + offsets can be both zero. + + @@ -283,7 +519,7 @@ Gdk.Pixbuf - + @@ -293,17 +529,116 @@ - To be added - To be added: an object of type 'Gdk.Drawable' - To be added: an object of type 'Gdk.Colormap' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'Gdk.Pixbuf' - To be added + Gets image from a Gdk.Drawable + Source drawable (A ) + A colormap (if src does not have one set) (A + Source X coordinate within drawable. + Source Y coordinate within drawable. + Destination X coordinate in pixbuf, or 0 + if dest is . + Destination Y coordinate in pixbuf, or 0 + if dest is . + Width in pixels of region to get. + Height in pixels of region to get. + + + The value of the Pixbuf (the same one that was passed) or + on error. See the remarks below + for details on the possible ways on which this function + might fail. + + + + + Transfers image data from a + and converts it to an RGB(A) representation inside a . 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. + + + If the has no colormap ( returns ), then a suitable colormap must be + specified. Typically a or a + pixmap created by passing a to + the constructor will already + have a colormap associated with it. If the has a colormap, the argument will be ignored. If the is a bitmap (1 bit per pixel pixmap), + then a colormap is not required; pixels with a value of 1 + are assumed to be white, and pixels with a value of 0 are + assumed to be black. For taking screenshots, the property returns the + correct colormap to use. + + + + If the specified destination pixbuf is , then this + function will create an RGB Pixbuf with 8 bits per channel + and no alpha, with the same size specified by the width + and height arguments. In this case, the and arguments + must be specified as 0. If the specified destination + pixbuf is not and it contains alpha + information, then the filled pixels will be set to full + opacity (alpha = 255). + + + + If the specified is a pixmap, + then the requested source rectangle must be completely + contained within the pixmap, otherwise the function will + return . For pixmaps only (not for + windows) passing -1 for or + is allowed, to mean the full + width or height of the pixmap. + + + + If the specified is a window, + and 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 corresponding to the offscreen + region are undefined. + + + + If the window you are 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 target drawable is not mapped (typically because + it's iconified/minimized or not on the current workspace), + then will be returned. + + + + If memory can't be allocated for the return value, will be returned instead. + + + + (In short, there are several ways this function can fail, + and if it fails it returns ; so + check the return value.) + + + + This function calls + internally and converts the resulting image to a , so the documentation for is also + relevant. + + @@ -314,9 +649,13 @@ - To be added - To be added: an object of type 'Gdk.Pixbuf' - To be added + Copies the Pixbuf + + + A copy of the data in the Pixbuf, or on failure + + + @@ -389,19 +728,30 @@ - To be added - To be added: an object of type 'Gdk.Pixbuf' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'double' - To be added: an object of type 'double' - To be added: an object of type 'double' - To be added: an object of type 'double' - To be added: an object of type 'Gdk.InterpType' - To be added: an object of type 'int' - To be added + Scale and Compose a Pixbuf + The destination Pixbuf to render to. + The left coordinate for region to render + The top coordinate for region to render + The width of the region to render + The height of the region to render + The offset in the X direction (currently rounded to an integer) + The offset in the Y direction (currently rounded to an integer) + The scale factor in the X direction + The scale factor in the Y direction + The interpolation type for the transformation. + Overall alpha for source image (0..255) + + + Creates a transformation of the Pixbuf by scaling by + and + then translating by and + , then composites the rectangle + (, , + , ) of the resulting image onto the + destination image. + + @@ -423,18 +773,36 @@ - To be added - To be added: an object of type 'Gdk.Pixbuf' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'double' - To be added: an object of type 'double' - To be added: an object of type 'double' - To be added: an object of type 'double' - To be added: an object of type 'Gdk.InterpType' - To be added + Scale transformation. + The destination Pixbuf where the results + are rendered + The left coordinate for region to render + The top coordinate for region to render + The width of the region to render + The height of the region to render + The offset in the X direction (currently rounded to an integer) + The offset in the Y direction (currently rounded to an integer) + The scale factor in the X direction + The scale factor in the Y direction + The interpolation type for the transformation. + + + Creates a transformation of the Pixbuf by scaling to + and + then translating by and + , then renders the rectangle + (, , + , ) of the resulting image onto the + destination image replacing the previous contents. + + + Try to use , this + function is the industrial-strength power tool you can + fall back to if is + not powerful enough. + + @@ -453,15 +821,21 @@ - To be added - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'Gdk.Pixbuf' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added + Copies a region from one Pixbuf to another + Source X coordinate within src_pixbuf. + Source Y coordinate within src_pixbuf + Width of the area to copy. + Height of the area to copy. + Destination Pixbuf. + X coordinate within dest_pixbuf. + Y coordinate within dest_pixbuf. + + + Copies a rectangular area from src_pixbuf to + dest_pixbuf. Conversion of pixbuf formats is done + automatically. + + @@ -474,9 +848,17 @@ - To be added - To be added: an object of type 'uint' - To be added + + Fills a pixbuf with a single color + + RGBA value for the pixel to set (0xffffffff is opaque white, 0x00000000 transparent black) + + + Clears a pixbuf to the given RGBA value, converting the + RGBA value into the pixbuf's pixel format. The alpha will + be ignored if the Pixbuf does not have an alpha channel. + + @@ -489,10 +871,15 @@ - To be added - To be added: an object of type 'string' - To be added: an object of type 'string' - To be added + Looks up an option in the Pixbuf + the key to lookup + The value associated with the + + + Looks up key in the list of options that may have been + attached to the pixbuf when it was loaded. + + @@ -526,11 +913,25 @@ - To be added - To be added: an object of type 'Gdk.Pixbuf' - To be added: an object of type 'float' - To be added: an object of type 'bool' - To be added + Saturation and pixelation of a Pixbuf + Target Pixbuf where the resulting image is stored + saturation factor + whether to pixelation will take place + + + Modifies saturation and optionally pixelates the Pixbuf, + placing the result in . may be the same Pixbuf with no ill + effects. If is 1.0 then + saturation is not changed. If it's less than 1.0, + saturation is reduced (the image is darkened); if greater + than 1.0, saturation is increased (the image is + brightened). If is , then pixels are faded in a checkerboard + pattern to create a pixelated image. src and dest must + have the same image format, size, and rowstride. + + @@ -612,10 +1013,17 @@ - To be added - To be added: an object of type 'uint' - To be added: an object of type 'Gdk.Pixbuf' - To be added + Internal constructor + GLib type for the type + Creates a new instance of the Pixbuf, using the + GLib-provided type + + + This is a constructor used by derivative types of that would have their own GLib type + assigned to it. This is not typically used by C# code. + + @@ -626,10 +1034,15 @@ - To be added - To be added: an object of type 'IntPtr' - To be added: an object of type 'Gdk.Pixbuf' - To be added + Internal constructor + Pointer to the C object. + An instance of Pixbuf, wrapping the C object. + + + This is an internal constructor, and should not be used by + user code. + + @@ -644,14 +1057,20 @@ - To be added - To be added: an object of type 'Gdk.Colorspace' - To be added: an object of type 'bool' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'Gdk.Pixbuf' - To be added + Constructor + The colorspace () + Whether the image should have transparency information. + Number of bits per color sample. + Width of image in pixels. + Height of image in pixels. + + + Creates a new structure and allocates a buffer + for it. The buffer has an optimal rowstride. Note that the + buffer is not cleared; you will have to fill it completely + yourself. + + @@ -690,10 +1109,16 @@ - To be added - To be added: an object of type 'string' - To be added: an object of type 'Gdk.Pixbuf' - To be added + Creates Pixbuf from image file. + Filename with the image + + + Creates a new pixbuf by loading an image from a file. The + file format is detected automatically (multiple formats are + supported: JPG, PNG, TIFF, XPM, XBM). If the file is not + found, a will be thrown. + + @@ -726,14 +1151,22 @@ - To be added - To be added: an object of type 'Gdk.Pixbuf' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'int' - To be added: an object of type 'Gdk.Pixbuf' - To be added + Creates a sub-Pixbuf from an existing one. + The containing . + X coord in src_pixbuf + Y coord in src_pixbuf + Width of region in src_pixbuf + Height of region in src_pixbuf + + + Creates a new pixbuf which represents a sub-region of + . The new pixbuf shares its + pixels with the original pixbuf, so writing to one affects + both. The new pixbuf holds a reference to , so will + not be finalized until the new pixbuf is finalized. + + @@ -748,21 +1181,26 @@ - + Constructor - To be added - To be added: an object of type '' - To be added: an object of type 'Gdk.Pixbuf' - To be added + Creates a Pixbuf from an image stored in a Stream + Input stream. + + + A pixbuf is constructed from an image file in the incoming + stream. The image file can be in any of the formats + supported by the Pixbuf. + + - + Constructor @@ -770,11 +1208,34 @@ - To be added - To be added: an object of type '' - To be added: an object of type 'string' - To be added: an object of type 'Gdk.Pixbuf' - To be added + Loads an image from an assembly resource + The assembly to load the image from (or + for the default assembly. + The resource name given to the image to + load. + + + A Pixbuf is constructed from the image file stored in the + resources of specified assembly. If the specified + assembly is null, then the code will load the resource + from the same assembly as the calling assembly (It uses + + to determine the calling assembly). + + + To link an image file into your program, invoke the + compiler with the /resource: flag, like this: + + mcs -resource:logo.png program.cs + + if you want to specify a pathname different than the ID, + you can pass those two flags: + + mcs -resource:/usr/local/bin/logo.png,logo.png program.cs + + + @@ -784,9 +1245,9 @@ System.UInt32 - To be added - To be added: an object of type 'uint' - To be added + The GLib Type for Gdk.Pixbuf + The GLib TYpe for the Gdk.Pixbuf class. + @@ -796,9 +1257,9 @@ System.Int32 - To be added - To be added: an object of type 'int' - To be added + Number of bits per color sample in a pixbuf. + The number of bits per color sample in the pixbuf + None. @@ -808,9 +1269,9 @@ System.Int32 - To be added - To be added: an object of type 'int' - To be added + Height of the image + The height in pixels of the image + None. @@ -832,9 +1293,16 @@ System.Boolean - To be added - To be added: an object of type 'bool' - To be added + Returns whether the Pixbuf contains an alpha channel + if the image contains an Alpha + channel, otherwise. + + + The Pixbuf object handles images in either the RGB format, + or the RGBA format. The alpha channel value is a value + between 0 and 255 and controls the opacity of a given pixel. + + @@ -844,9 +1312,9 @@ System.Int32 - To be added - To be added: an object of type 'int' - To be added + The width of the image + The width in pixels of the image + None. @@ -856,9 +1324,10 @@ System.Int32 - To be added - To be added: an object of type 'int' - To be added + The number of channels on a Pixbuf + Returns the number of channels on a Pixbuf + + @@ -868,9 +1337,13 @@ System.Int32 - To be added - To be added: an object of type 'int' - To be added + Rowstride of the Pixbuf + The rowstride property for the Pixbuf + + + Queries the rowstride of a pixbuf, which is the number of bytes between rows. + + @@ -880,9 +1353,13 @@ Gdk.Colorspace - To be added - To be added: an object of type 'Gdk.Colorspace' - To be added + The colorspace for this Pixbuf + The colorspace used by this Pixbuf + + + Currently Pixbuf only support the RGB colorspace. + +