xtd 0.2.0
xtd::drawing::image Class Reference

#include <image.h>

## Definition

An abstract base class that provides functionality for the bitmap and metafile descended classes.

class drawing_export_ image : public xtd::object
Inheritance
xtd::objectxtd::drawing::image
Namespace
xtd::drawing
Library
xtd.drawing
Remarks
To draw an image on a Windows Form, you should use one of the draw_image methods.
Examples:
draw_image.cpp, fill_ellipse.cpp, fill_rectangle.cpp, fill_rounded_rectangle.cpp, status_bar.cpp, and toggle_button2.cpp.

## Fields

static image empty
Represent an empty xtd::drawing::image. More...

## Properties

int32 flags () const noexcept
Gets attribute flags for the pixel data of this xtd::drawing::image. More...

std::vector< guidframe_dimentions_list () const noexcept
Gets an array of GUIDs that represent the dimensions of frames within this image. More...

intptr handle () const noexcept
Gets the handle of this image. More...

int32 height () const noexcept
Gets the height, in pixels, of this image. More...

float horizontal_resolution () const noexcept
Gets the horizontal resolution, in pixels per inch, of this image. More...

imaging::color_palette palette () const noexcept
Gets the color palette used for this image. More...

void palette (const imaging::color_palette &palette) noexcept
Sets the color palette used for this image. More...

const size_fphysical_dimension () const noexcept
Gets the width and height of this image. More...

imaging::pixel_format pixel_format () const noexcept
Gets the pixel format for this image. More...

const std::vector< int32 > & property_id_list () const noexcept
Gets IDs of the property items stored in this image. More...

const std::vector< imaging::property_item > & property_items () const noexcept
Gets all the property items (pieces of metadata) stored in this image. More...

const imaging::image_formatraw_format () const noexcept
Gets the file format of this image. More...

const drawing::sizesize () const noexcept
Gets the width and height, in pixels, of this image. More...

const std::anytag () const noexcept

void tag (const std::any &tag) noexcept

float vertical_resolution () const noexcept
Gets the vertical resolution, in pixels per inch, of this image. More...

int32 width () const noexcept
Gets the width, in pixels, of this image. More...

## Methods

Blurs the image whith the specified radius. More...

graphics create_graphics ()
Creates the xtd::drawing::graphics for the image. More...

bool equals (const image &image) const noexcept override

xtd::drawing::rectangle_f get_bounds (xtd::drawing::graphics_unit page_unit) const noexcept
Gets the bounds of the image in the specified unit. More...

xtd::drawing::imaging::encoder_parameters get_encoder_parameter_list (xtd::guid encoder) const noexcept
Returns information about the parameters supported by the specified image encoder. More...

size_t get_frame_count (const xtd::drawing::imaging::frame_dimension &dimension) const
Returns the number of frames of the specified dimension. More...

xtd::drawing::imaging::property_item get_property_item (int32 propid)
Gets the specified property item from this xtd::drawing::image. More...

xtd::drawing::image get_thmbnail_image (int32 thumb_width, int32 thunb_height) noexcept
Returns a thumbnail for this xtd::drawing::image. More...

void rotate_flip (xtd::drawing::rotate_flip_type rotate_flip_type)
Rotates, flips, or rotates and flips the xtd::drawing::image. More...

void save (const xtd::ustring &filename) const
Saves this xtd::drawing::image to the specified file or stream. More...

void save (const xtd::ustring &filename, const xtd::drawing::imaging::image_format &format) const
Saves this xtd::drawing::image to the specified file in the specified format. More...

void save (std::ostream &stream, const xtd::drawing::imaging::image_format &format) const
Saves this image to the specified stream in the specified format. More...

static image from_file (const xtd::ustring &filename)
Creates an image from the specified file. More...

static bitmap from_hbitmap (intptr hbitmap)
Creates a xtd::drawing::bitmap from a handle to a GDI bitmap. More...

static image from_stream (std::istream &stream)
Creates an xtd::drawing::image from the specified data stream. More...

static image from_data (const char *const *bits)
Creates an xtd::drawing::image from the specified data pointer. More...

static int32 get_pixel_format_size (xtd::drawing::imaging::pixel_format pixfmt) noexcept
Returns the color depth, in number of bits per pixel, of the specified pixel format. More...

static bool is_alpha_pixel_format (xtd::drawing::imaging::pixel_format pixfmt) noexcept
Returns a value that indicates whether the pixel format for this xtd::drawing::image contains alpha information. More...

static bool is_canonical_pixel_format (xtd::drawing::imaging::pixel_format pixfmt) noexcept
Returns a value that indicates whether the pixel format is 32 bits per pixel. More...

static bool is_extended_pixel_format (xtd::drawing::imaging::pixel_format pixfmt) noexcept
Returns a value that indicates whether the pixel format is 64 bits per pixel. More...

Public Member Functions inherited from xtd::object
object ()=default
Create a new instance of the ultimate base class object. More...

bool equals (const object &obj) const noexcept
Determines whether the specified object is equal to the current object. More...

virtual size_t get_hash_code () const noexcept
Serves as a hash function for a particular type. More...

template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const noexcept
Gets the type of the current instance. More...

virtual xtd::ustring to_string () const noexcept
Returns a sxd::ustring that represents the current object. More...

Public Member Functions inherited from xtd::iequatable< image >
virtual bool equals (const image &) const noexcept=0
Indicates whether the current object is equal to another object of the same type. More...

Static Public Member Functions inherited from xtd::object
static bool equals (const object &object_a, const object &object_b) noexcept
Determines whether the specified object instances are considered equal. More...

static bool reference_equals (const object &object_a, const object &object_b) noexcept
Determines whether the specified object instances are the same instance. More...

## ◆ blur()

 image xtd::drawing::image::blur ( int32 radius ) const

Blurs the image whith the specified radius.

Parameters
Note
No blur effect, if the radius is 0.
Returns
The new blurred image.

## ◆ flags()

 int32 xtd::drawing::image::flags ( ) const
noexcept

Gets attribute flags for the pixel data of this xtd::drawing::image.

Returns
The integer representing a bitwise combination of xtd::drawing::imaging::image_flags for this xtd::drawing::image.
Remarks
The integer value returned from this method will correspond to a sum of image_flags, as described in the following table.
image_flag value Integer representation
image_flags_none 0
Iimage_flags_scalable 1
Iimage_flags_has_alpha 2
Iimage_flags_has_translucent 4
Iimage_flags_partially_scalable 8
Iimage_flags_color_space_rgb 16
Iimage_flags_color_space_cmyk 32
Iimage_flags_color_space_gray 64
Iimage_flags_color_space_ycbr 128
Iimage_flags_color_space_ycck 256
Iimage_flags_has_real_dpi 4096
Iimage_flags_has_real_pixel_size 8192
Iimage_flags_caching 131072
For example, if the Flags property for an image returned 77960, the image_flags for the image would be read_only, has_real_dpi, has_real_pixel_size, color_space_ycbcr, and partially_scalable.

## ◆ frame_dimentions_list()

 std::vector xtd::drawing::image::frame_dimentions_list ( ) const
noexcept

Gets an array of GUIDs that represent the dimensions of frames within this image.

Returns
An array of GUIDs that specify the dimensions of frames within this xtd::drawing::image from most significant to least significant.
Remarks
This method returns information about multiple-frame images, which come in two styles: multiple page and multiple resolution.
A multiple-page image is an image that contains more than one image. Each page contains a single image (or frame). These pages (or images, or frames) are typically displayed in succession to produce an animated sequence, such as an animated .gif file.
A multiple-resolution image is an image that contains more than one copy of an image at different resolutions. This is commonly used by MIP mapping where the displayed image size determines the resolution of the image used for drawing. GDI+ can support an arbitrary number of pages (or images, or frames), as well as an arbitrary number of resolutions. The defined dimensions are properties of the frame_dimension.

## ◆ from_data()

 static image xtd::drawing::image::from_data ( const char *const * bits )
static

Creates an xtd::drawing::image from the specified data pointer.

Parameters
 data A pointer that contains the data for this xtd::drawing::image.
Returns
The xtd::drawing::image this method creates.
Remarks
This method is used for creating a xtd::drawing::image from an XPM (or XBM) image.
Examples:
bitmap_button.cpp, and flat_button.cpp.

## ◆ from_file()

 static image xtd::drawing::image::from_file ( const xtd::ustring & filename )
inlinestatic

Creates an image from the specified file.

Parameters
 filename A string that contains the name of the file from which to create the image.
Returns
The xtd::drawing::image this method creates.
Examples:
image_list.cpp.

## ◆ from_hbitmap()

 static bitmap xtd::drawing::image::from_hbitmap ( intptr hbitmap )
static

Creates a xtd::drawing::bitmap from a handle to a GDI bitmap.

Parameters
 hbitmap The GDI bitmap handle from which to create the xtd::drawing::bitmap.
Returns
The xtd::drawing::bitmap this method creates.
Remarks
The xtd::drawing::image::from_hbitmap method makes a copy of the GDI bitmap; so you can release the incoming GDI bitmap using the GDI DeleteObject method immediately after creating the new xtd::drawing::image.

## ◆ from_stream()

 static image xtd::drawing::image::from_stream ( std::istream & stream )
static

Creates an xtd::drawing::image from the specified data stream.

Parameters
 stream A std::istream that contains the data for this xtd::drawing::image.
Returns
The xtd::drawing::image this method creates.
Remarks
You must keep the stream open for the lifetime of the xtd::drawing::image.
Note
The xtd::drawing::image class does not support alpha transparency in bitmaps. To enable alpha transparency, use PNG images with 32 bits per pixel.

## ◆ get_bounds()

 xtd::drawing::rectangle_f xtd::drawing::image::get_bounds ( xtd::drawing::graphics_unit page_unit ) const
noexcept

Gets the bounds of the image in the specified unit.

Parameters
 page_unit One of the xtd::drawing::graphics_unit values indicating the unit of measure for the bounding rectangle.
Returns
The xtd::drawing::rectangle_f that represents the bounds of the image, in the specified unit.

## ◆ get_encoder_parameter_list()

 xtd::drawing::imaging::encoder_parameters xtd::drawing::image::get_encoder_parameter_list ( xtd::guid encoder ) const
noexcept

Returns information about the parameters supported by the specified image encoder.

Parameters
 guid A GUID that specifies the image encoder.
Returns
An xtd::drawing::imaging::encoder_parameters that contains an array of xtd::drawing::imaging::encoder_parameter objects. Each xtd::drawing::imaging::encoder_parameter contains information about one of the parameters supported by the specified image encoder.

## ◆ get_frame_count()

 size_t xtd::drawing::image::get_frame_count ( const xtd::drawing::imaging::frame_dimension & dimension ) const

Returns the number of frames of the specified dimension.

Parameters
 dimension A xtd::drawing::imaging::frame_dimension that specifies the identity of the dimension type.
Returns
The number of frames in the specified dimension.
Remarks
This method returns information about multiple-frame images, which come in two styles: multiple page and multiple resolution.
A multiple-page image is an image that contains more than one image. Each page contains a single image (or frame). These pages (or images, or frames) are typically displayed in succession to produce an animated sequence, such as an animated .gif file.
A multiple-resolution image is an image that contains more than one copy of an image at different resolutions. This is commonly used by MIP mapping where the displayed image size determines the resolution of the image used for drawing. GDI+ can support an arbitrary number of pages (or images, or frames), as well as an arbitrary number of resolutions. The defined dimensions are properties of the xtd::drawing::imaging::frame_dimension.

## ◆ get_pixel_format_size()

 static int32 xtd::drawing::image::get_pixel_format_size ( xtd::drawing::imaging::pixel_format pixfmt )
staticnoexcept

Returns the color depth, in number of bits per pixel, of the specified pixel format.

Parameters
 pixfmt The xtd::drawing::imaging::pixel_format member that specifies the format for which to find the size.
Returns
The color depth of the specified pixel format.

## ◆ get_property_item()

 xtd::drawing::imaging::property_item xtd::drawing::image::get_property_item ( int32 propid )

Gets the specified property item from this xtd::drawing::image.

Parameters
 propid The ID of the property item to get.
Returns
The xtd::drawing::imaging::property_item this method gets.
Exceptions
 xtd::argument_exception The image format of this image does not support property items.
Remarks
It is difficult to set property items, because the xtd::drawing::imaging::property_item class has no public constructors. One way to work around this restriction is to obtain a xtd::drawing::imaging::property_item by retrieving the xtd::drawing::image::property_item property value or calling the xtd::drawing::image::get_property_item method of an xtd::drawing::image that already has property items. Then you can set the fields of the xtd::drawing::imaging::property_item and pass it to xtd::drawing::image::set_property_item.

## ◆ get_thmbnail_image()

 xtd::drawing::image xtd::drawing::image::get_thmbnail_image ( int32 thumb_width, int32 thunb_height )
noexcept

Returns a thumbnail for this xtd::drawing::image.

Parameters
 thbmb_width The width, in pixels, of the requested thumbnail image. thum_height The height, in pixels, of the requested thumbnail image.
Returns
An xtd::drawing::image that represents the thumbnail.
Remarks
If the xtd::drawing::image contains an embedded thumbnail image, this method retrieves the embedded thumbnail and scales it to the requested size. If the xtd::drawing::image does not contain an embedded thumbnail image, this method creates a thumbnail image by scaling the main image.
The xtd::drawing::image::get_thumbnail_image method works well when the requested thumbnail image has a size of about 120 x 120 pixels. If you request a large thumbnail image (for example, 300 x 300) from an xtd::drawing::image that has an embedded thumbnail, there could be a noticeable loss of quality in the thumbnail image. It might be better to scale the main image (instead of scaling the embedded thumbnail) by calling the xtd::drawing::graphics::draw_image method.

## ◆ handle()

 intptr xtd::drawing::image::handle ( ) const
noexcept

Gets the handle of this image.

Returns
The handle of this image.
Examples:
image.cpp.

## ◆ height()

 int32 xtd::drawing::image::height ( ) const
noexcept

Gets the height, in pixels, of this image.

Returns
The height, in pixels, of this image.
Examples:
colored_tab_pages.cpp, graphics.cpp, status_bar.cpp, and toggle_button2.cpp.

## ◆ horizontal_resolution()

 float xtd::drawing::image::horizontal_resolution ( ) const
noexcept

Gets the horizontal resolution, in pixels per inch, of this image.

Returns
The horizontal resolution, in pixels per inch, of this image.
Examples:
image.cpp.

## ◆ is_alpha_pixel_format()

 static bool xtd::drawing::image::is_alpha_pixel_format ( xtd::drawing::imaging::pixel_format pixfmt )
staticnoexcept

Returns a value that indicates whether the pixel format for this xtd::drawing::image contains alpha information.

Parameters
 pixfmt The PixelFormat to test.
Returns
true if pixfmt contains alpha information; otherwise, false.

## ◆ is_canonical_pixel_format()

 static bool xtd::drawing::image::is_canonical_pixel_format ( xtd::drawing::imaging::pixel_format pixfmt )
staticnoexcept

Returns a value that indicates whether the pixel format is 32 bits per pixel.

Parameters
 pixfmt The PixelFormat to test.
Returns
true if pixfmt is canonical; otherwise, false.

## ◆ is_extended_pixel_format()

 static bool xtd::drawing::image::is_extended_pixel_format ( xtd::drawing::imaging::pixel_format pixfmt )
staticnoexcept

Returns a value that indicates whether the pixel format is 64 bits per pixel.

Parameters
 pixfmt The PixelFormat to test.
Returns
true if pixfmt is extended; otherwise, false.

## ◆ palette() [1/2]

 imaging::color_palette xtd::drawing::image::palette ( ) const
noexcept

Gets the color palette used for this image.

Returns
An xtd::drawing::imaging::color_palette that represents the color palette used for this image.
Remarks
This property returns a copy of the xtd::drawing::imaging::color_palette object used by this xtd::drawing::image.

## ◆ palette() [2/2]

 void xtd::drawing::image::palette ( const imaging::color_palette & palette )
noexcept

Sets the color palette used for this image.

Parameters
 palette A color_palette that represents the color palette used for this image.

## ◆ physical_dimension()

 const size_f& xtd::drawing::image::physical_dimension ( ) const
noexcept

Gets the width and height of this image.

Returns
A xtd::drawing::size_f structure that represents the width and height of this image.
Remarks
If the image is a bitmap, the width and height are returned in pixels. If the image is a metafile, the width and height are returned in 0.01 millimeter units.
Examples:
image.cpp.

## ◆ pixel_format()

 imaging::pixel_format xtd::drawing::image::pixel_format ( ) const
noexcept

Gets the pixel format for this image.

Returns
A pixel_format that represents the pixel format for this image.

## ◆ property_id_list()

 const std::vector& xtd::drawing::image::property_id_list ( ) const
noexcept

Gets IDs of the property items stored in this image.

Returns
An array of the property IDs, one for each property item stored in this image.
Remarks
If the image has no property items or if the image format does not support property items, the property_id_list property returns an empty array (that is, an array of length zero).

## ◆ property_items()

 const std::vector& xtd::drawing::image::property_items ( ) const
noexcept

Gets all the property items (pieces of metadata) stored in this image.

Returns
An array of xtd::drawing::imaging::property_item objects, one for each property item stored in the image.
Remarks
IIf the image has no property items or if the image format does not support property items, property_items returns an empty array (that is, an array of length zero).

## ◆ raw_format()

 const imaging::image_format& xtd::drawing::image::raw_format ( ) const
noexcept

Gets the file format of this image.

Returns
The image_format that represents the file format of this image.
Examples:
image.cpp.

## ◆ rotate_flip()

 void xtd::drawing::image::rotate_flip ( xtd::drawing::rotate_flip_type rotate_flip_type )

Rotates, flips, or rotates and flips the xtd::drawing::image.

Parameters
 rotate_flip_type A xtd::drawing::rotate_flip_type member that specifies the type of rotation and flip to apply to the image.
Remarks
The xtd::drawing::image::rotate_flip method rotates the image clockwise.
If you wish to draw on an image once it has been rotated, you should always retrieve a new graphics object from the image, otherwise an exception could occur.

## ◆ save() [1/3]

 void xtd::drawing::image::save ( const xtd::ustring & filename ) const

Saves this xtd::drawing::image to the specified file or stream.

Parameters
 filename A string that contains the name of the file to which to save this xtd::drawing::image.
Remarks
If no encoder exists for the file format of the image, the Portable Network Graphics (PNG) encoder is used. When you use the xtd::drawing::image::save method to save a graphic image as a Windows Metafile Format (WMF) or Enhanced Metafile Format (EMF) file, the resulting file is saved as a Portable Network Graphics (PNG) file. This behavior occurs because the GDI+ component of the .NET Framework does not have an encoder that you can use to save files as .wmf or .emf files.
Saving the image to the same file it was constructed from is not allowed and throws an exception.
Examples:
graphics.cpp, and hello_world_png.cpp.

## ◆ save() [2/3]

 void xtd::drawing::image::save ( const xtd::ustring & filename, const xtd::drawing::imaging::image_format & format ) const

Saves this xtd::drawing::image to the specified file in the specified format.

Parameters
 filename A string that contains the name of the file to which to save this xtd::drawing::image. format The xtd::drawing::imaging::image_format for this xtd::drawing::image.

## ◆ save() [3/3]

 void xtd::drawing::image::save ( std::ostream & stream, const xtd::drawing::imaging::image_format & format ) const

Saves this image to the specified stream in the specified format.

Parameters
 stream The std::otream where the image will be saved. format The xtd::drawing::imaging::image_format for this xtd::drawing::image.
Remarks
You should avoid saving an image to the same stream that was used to construct it. Doing so might damage the stream.
The image must be saved to the stream at an offset of zero. If any additional data has been written to the stream before saving the image, the image data in the stream will be corrupted.

## ◆ size()

 const drawing::size& xtd::drawing::image::size ( ) const
noexcept

Gets the width and height, in pixels, of this image.

Returns
A size structure that represents the width and height, in pixels, of this image.
Examples:
hello_world_png.cpp, image.cpp, and painting.cpp.

## ◆ tag() [1/2]

 const std::any& xtd::drawing::image::tag ( ) const
noexcept

Returns

## ◆ tag() [2/2]

 void xtd::drawing::image::tag ( const std::any & tag )
noexcept

Parameters

## ◆ vertical_resolution()

 float xtd::drawing::image::vertical_resolution ( ) const
noexcept

Gets the vertical resolution, in pixels per inch, of this image.

Returns
The vertical resolution, in pixels per inch, of this image.
Examples:
image.cpp.

## ◆ width()

 int32 xtd::drawing::image::width ( ) const
noexcept

Gets the width, in pixels, of this image.

Returns
The width, in pixels, of this image.
Examples:
colored_tab_pages.cpp, graphics.cpp, status_bar.cpp, and toggle_button2.cpp.

## ◆ empty

 image xtd::drawing::image::empty
static

The documentation for this class was generated from the following file:
• xtd.drawing/include/xtd/drawing/image.h