xtd 0.2.0
Loading...
Searching...
No Matches
xtd::drawing::image Class Reference
Inheritance diagram for xtd::drawing::image:
xtd::object xtd::iequatable< image > xtd::interface xtd::drawing::bitmap

Definition

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

class drawing_export_ image : public xtd::object, public xtd::iequatable<image>
An abstract base class that provides functionality for the bitmap and metafile descended classes.
Definition image.h:49
Defines a generalized method that a value type or class implements to create a type-specific method f...
Definition iequatable.h:18
Supports all classes in the xtd class hierarchy and provides low-level services to derived classes....
Definition object.h:32
#define drawing_export_
Define shared library export.
Definition drawing_export.h:13
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, image_converter.cpp, and toggle_button2.cpp.

Public Fields

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

Public Properties

int32 flags () const noexcept
 Gets attribute flags for the pixel data of this xtd::drawing::image.
 
std::vector< guidframe_dimentions_list () const noexcept
 Gets an array of GUIDs that represent the dimensions of frames within this image.
 
intptr handle () const noexcept
 Gets the handle of this image.
 
int32 height () const noexcept
 Gets the height, in pixels, of this image.
 
float horizontal_resolution () const noexcept
 Gets the horizontal resolution, in pixels per inch, of this image.
 
imaging::color_palette palette () const noexcept
 Gets the color palette used for this image.
 
void palette (const imaging::color_palette &palette) noexcept
 Sets the color palette used for this image.
 
const size_fphysical_dimension () const noexcept
 Gets the width and height of this image.
 
imaging::pixel_format pixel_format () const noexcept
 Gets the pixel format for this image.
 
const std::vector< int32 > & property_id_list () const noexcept
 Gets IDs of the property items stored in this image.
 
const std::vector< imaging::property_item > & property_items () const noexcept
 Gets all the property items (pieces of metadata) stored in this image.
 
const imaging::image_formatraw_format () const noexcept
 Gets the file format of this image.
 
const drawing::sizesize () const noexcept
 Gets the width and height, in pixels, of this image.
 
const std::any & tag () const noexcept
 Gets an object that provides additional data about the image.
 
void tag (const std::any &tag) noexcept
 Sets an object that provides additional data about the image.
 
float vertical_resolution () const noexcept
 Gets the vertical resolution, in pixels per inch, of this image.
 
int32 width () const noexcept
 Gets the width, in pixels, of this image.
 

Public Methods

image clone () const
 Creates an exact copy of this xtd::drawing::image.
 
graphics create_graphics ()
 Creates the xtd::drawing::graphics for the image.
 
bool equals (const image &image) const noexcept override
 
const xtd::byteget_alpha () const
 Gets the image alpha pointer, which represents the alpha data of the image.
 
xtd::byteget_alpha ()
 Gets the image alpha pointer, which represents the alpha data of the image.
 
xtd::drawing::rectangle_f get_bounds (xtd::drawing::graphics_unit page_unit) const noexcept
 Gets the bounds of the image in the specified unit.
 
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.
 
size_t get_frame_count (const xtd::drawing::imaging::frame_dimension &dimension) const
 Returns the number of frames of the specified dimension.
 
xtd::drawing::imaging::property_item get_property_item (int32 propid)
 Gets the specified property item from this xtd::drawing::image.
 
const xtd::byteget_rgb () const
 Gets the image data pointer, which represents the RGB data of the image.
 
xtd::byteget_rgb ()
 Gets the image data pointer, which represents the RGB data of the image.
 
xtd::drawing::image get_thmbnail_image (int32 thumb_width, int32 thunb_height) noexcept
 Returns a thumbnail for this xtd::drawing::image.
 
void rotate_flip (xtd::drawing::rotate_flip_type rotate_flip_type)
 Rotates, flips, or rotates and flips the xtd::drawing::image.
 
void save (const xtd::ustring &filename) const
 Saves this xtd::drawing::image to the specified file or stream.
 
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.
 
void save (std::ostream &stream, const xtd::drawing::imaging::image_format &format) const
 Saves this image to the specified stream in the specified format.
 

Public Static Methods

static image from_file (const xtd::ustring &filename)
 Creates an image from the specified file.
 
static bitmap from_hbitmap (intptr hbitmap)
 Creates a xtd::drawing::bitmap from a handle to a GDI bitmap.
 
static image from_stream (std::istream &stream)
 Creates an xtd::drawing::image from the specified data stream.
 
static image from_data (const char *const *bits)
 Creates an xtd::drawing::image from the specified data pointer.
 
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.
 
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.
 
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.
 
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.
 

Additional Inherited Members

- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object.
 
bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current object.
 
virtual size_t get_hash_code () const noexcept
 Serves as a hash function for a particular type.
 
virtual type_object get_type () const noexcept
 Gets the type of the current instance.
 
template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const noexcept
 Creates a shallow copy of the current object.
 
virtual xtd::ustring to_string () const noexcept
 Returns a xtd::ustring that represents the current object.
 
- 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.
 
- 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.
 
static bool reference_equals (const object &object_a, const object &object_b) noexcept
 Determines whether the specified object instances are the same instance.
 

Member Function Documentation

◆ clone()

image xtd::drawing::image::clone ( ) const

Creates an exact copy of this xtd::drawing::image.

Returns
The xtd::drawing::image this method creates.

◆ create_graphics()

graphics xtd::drawing::image::create_graphics ( )

Creates the xtd::drawing::graphics for the image.

Returns
A xtd::drawing::graphics for the 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_read_only 65536
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< guid > 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
dataA 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.

◆ from_file()

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

Creates an image from the specified file.

Parameters
filenameA string that contains the name of the file from which to create the image.
Returns
The xtd::drawing::image this method creates.

◆ 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
hbitmapThe 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
streamA 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_alpha() [1/2]

xtd::byte * xtd::drawing::image::get_alpha ( )

Gets the image alpha pointer, which represents the alpha data of the image.

Returns
The pointer or alpha image.
Remarks
The size of this data is 1 byte (alpha) * height() * width().
If the image has no handle, such as an empty image, this method returns nullptr.
Warning
Be careful when using this pointer as there is no control and you can exceed its size and create irreparable problems.
Remarks
To access the position of a specific pixel, it's best to use the xtd::drawing::image::get_pixel and xtd::drawing::image::set_pixel methods.

◆ get_alpha() [2/2]

const xtd::byte * xtd::drawing::image::get_alpha ( ) const

Gets the image alpha pointer, which represents the alpha data of the image.

Returns
The pointer or alpha image.
Remarks
The size of this data is 1 byte (alpha) * height() * width().
If the image has no handle, such as an empty image, this method returns nullptr.
Warning
Be careful when using this pointer as there is no control and you can exceed its size and create irreparable problems.
Remarks
To access the position of a specific pixel, it's best to use the xtd::drawing::image::get_pixel and xtd::drawing::image::set_pixel methods.

◆ 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_unitOne 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
guidA 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
dimensionA 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
pixfmtThe 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
propidThe ID of the property item to get.
Returns
The xtd::drawing::imaging::property_item this method gets.
Exceptions
xtd::argument_exceptionThe image format of this image does not support property items.
Remarks
For a list of property item IDs and links to more information, see Id.
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_rgb() [1/2]

xtd::byte * xtd::drawing::image::get_rgb ( )

Gets the image data pointer, which represents the RGB data of the image.

Returns
The pointer or data image.
Remarks
This is most often used when doing direct image manipulation. The return value points to an array of characters in RGBRGBRGB... format in the top-to-bottom, left-to-right order, that is the first RGB triplet corresponds to the first pixel of the first row, the second one — to the second pixel of the first row and so on until the end of the first row, with second row following after it and so on.
The size of this data is 3 bytes (RGB) * height() * width().
If the image has no handle, such as an empty image, this method returns nullptr.
Warning
Be careful when using this pointer as there is no control and you can exceed its size and create irreparable problems.
Remarks
To access the position of a specific pixel, it's best to use the xtd::drawing::image::get_pixel and xtd::drawing::image::set_pixel methods.

◆ get_rgb() [2/2]

const xtd::byte * xtd::drawing::image::get_rgb ( ) const

Gets the image data pointer, which represents the RGB data of the image.

Returns
The pointer or data image.
Remarks
This is most often used when doing direct image manipulation. The return value points to an array of characters in RGBRGBRGB... format in the top-to-bottom, left-to-right order, that is the first RGB triplet corresponds to the first pixel of the first row, the second one — to the second pixel of the first row and so on until the end of the first row, with second row following after it and so on.
The size of this data is 3 bytes (RGB) * height() * width().
If the image has no handle, such as an empty image, this method returns nullptr.
Warning
Be careful when using this pointer as there is no control and you can exceed its size and create irreparable problems.
Remarks
To access the position of a specific pixel, it's best to use the xtd::drawing::image::get_pixel and xtd::drawing::image::set_pixel methods.

◆ 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_widthThe width, in pixels, of the requested thumbnail image.
thum_heightThe 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.

◆ 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
painting.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.

◆ 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
pixfmtThe 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
pixfmtThe 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
pixfmtThe 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
paletteA 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.

◆ 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< int32 > & 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< imaging::property_item > & 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.

◆ 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_typeA 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
filenameA 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
image_xpm.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
filenameA string that contains the name of the file to which to save this xtd::drawing::image.
formatThe 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
streamThe std::otream where the image will be saved.
formatThe 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
painting.cpp.

◆ tag() [1/2]

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

Gets an object that provides additional data about the image.

Returns
The object that provides additional data about the image.

◆ tag() [2/2]

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

Sets an object that provides additional data about the image.

Parameters
tagThe object that provides additional data about the image.

◆ 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.

◆ 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
painting.cpp.

Member Data Documentation

◆ empty


The documentation for this class was generated from the following file: