// ____ ______ __ // / __ \ / ____// / // / /_/ // / / / // / ____// /___ / /___ PixInsight Class Library // /_/ \____//_____/ PCL 2.4.23 // ---------------------------------------------------------------------------- // pcl/Bitmap.h - Released 2022-03-12T18:59:29Z // ---------------------------------------------------------------------------- // This file is part of the PixInsight Class Library (PCL). // PCL is a multiplatform C++ framework for development of PixInsight modules. // // Copyright (c) 2003-2022 Pleiades Astrophoto S.L. All Rights Reserved. // // Redistribution and use in both source and binary forms, with or without // modification, is permitted provided that the following conditions are met: // // 1. All redistributions of source code must retain the above copyright // notice, this list of conditions and the following disclaimer. // // 2. All redistributions in binary form must reproduce the above copyright // notice, this list of conditions and the following disclaimer in the // documentation and/or other materials provided with the distribution. // // 3. Neither the names "PixInsight" and "Pleiades Astrophoto", nor the names // of their contributors, may be used to endorse or promote products derived // from this software without specific prior written permission. For written // permission, please contact info@pixinsight.com. // // 4. All products derived from this software, in any form whatsoever, must // reproduce the following acknowledgment in the end-user documentation // and/or other materials provided with the product: // // "This product is based on software from the PixInsight project, developed // by Pleiades Astrophoto and its contributors (https://pixinsight.com/)." // // Alternatively, if that is where third-party acknowledgments normally // appear, this acknowledgment must be reproduced in the product itself. // // THIS SOFTWARE IS PROVIDED BY PLEIADES ASTROPHOTO AND ITS CONTRIBUTORS // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED // TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PLEIADES ASTROPHOTO OR ITS // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, // EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, BUSINESS // INTERRUPTION; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; AND LOSS OF USE, // DATA OR PROFITS) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE // POSSIBILITY OF SUCH DAMAGE. // ---------------------------------------------------------------------------- #ifndef __PCL_Bitmap_h #define __PCL_Bitmap_h /// \file pcl/Bitmap.h #ifndef __PCL_BUILDING_PIXINSIGHT_APPLICATION #include #include #include #include #include #include #endif // __PCL_BUILDING_PIXINSIGHT_APPLICATION namespace pcl { // ---------------------------------------------------------------------------- /*! * \namespace pcl::BitmapFormat * \brief Bitmap pixel value interpretation modes. * * * * * * * * *
BitmapFormat::ARGB32AARRGGBB format. The alpha AA component is used to represent the * transparency of each pìxel: from 0=transparent to 0xFF=opaque. * This is the default mode.
BitmapFormat::RGB32ffRRGGBB format. The alpha component is set to a constant value of * 255 = 0xff, hence the bitmap is always opaque. This mode can be used * to improve the performance of graphics output when painting on * controls, especially on X11 platforms (Linux and FreeBSD).
BitmapFormat::ARGB32_PremultipliedAARRGGBB format with red, green and blue components premultiplied by * the alpha channel and divided by 255. This format is faster for * bitmap renditions drawn with the Graphics and VectorGraphics * classes.
*/ namespace BitmapFormat { enum value_type { ARGB32, // AARRGGBB RGB32, // ffRRGGBB ARGB32_Premultiplied, // AARRGGBB with premultiplied RGB // ### TODO: Core version 1.8.x: Implement 16-bit bitmap formats. // RGBA64, // RRRRGGGGBBBBAAAA // RGBA64, // RRRRGGGGBBBBffff // RGBA64_Premultiplied, // RRRRGGGGBBBBAAAA with premultiplied RGB NumberOfBitmapFormats, Invalid = -1 }; } // ---------------------------------------------------------------------------- /*! * \namespace pcl::SVGRenderOption * \brief Rendering options for raster image representation of SVG documents. * * * * * * * * *
SVGRenderOption::PreserveAspectRatioRender within the specified rectangular area, preserving the * original aspect ratio of the SVG drawing. If not selected, render * freely to fill the specified rectangular area entirely.
SVGRenderOption::HighQualityRender with a high-quality, thread-unsafe implementation supporting * the entire SVG 1.1 specification. If not selected, use a fast * thread-safe implementation that supports most of the SVG 1.1 * specification.
SVGRenderOption::DefaultDefault rendering options: * SVGRenderOption::PreserveAspectRatio | SVGRenderOption::Fast
*/ namespace SVGRenderOption { enum mask_type { IgnoreAspectRatio = 0x00000000, // Render freely to fill the specified rectangular area entirely, ignoring aspect ratio. PreserveAspectRatio = 0x00000001, // Render within the specified rectangular area, preserving the original aspect ratio of the SVG drawing. Fast = 0x00000000, // Render with a fast, thread-safe implementation that supports most of the SVG 1.1 specification. HighQuality = 0x00000010, // Render with a high-quality, thread-unsafe implementation supporting the entire SVG 1.1 specification. Default = PreserveAspectRatio|Fast }; }; /*! * \class pcl::SVGRenderOptions * \brief A collection of rendering options for raster image representation of * SVG documents. */ typedef Flags SVGRenderOptions; // ---------------------------------------------------------------------------- #ifndef __PCL_BUILDING_PIXINSIGHT_APPLICATION class PCL_CLASS ImageVariant; // ---------------------------------------------------------------------------- /*! * \class Bitmap * \brief Client-side interface to a PixInsight %Bitmap object. * * In the PixInsight platform, bitmaps are device-independent images that can * be used for graphics output and allow direct pixel manipulation. * * Pixels in a bitmap are always stored as 32-bit values in the following * format: * * AARRGGBB * * where each letter represents a 4-bit hexadecimal digit (from 0 to F). Each * 8-bit pair represents a pixel component in the range from 0 to 255: * * * * * * *
AA Alpha value, or pixel opacity: 0 means * completely transparent, 255 corresponds to an opaque * pixel.
RR Red pixel color component.
GG Green pixel color component.
BB Blue pixel color component.
* * %Bitmap is a managed, high-level object that encapsulates the properties and * behavior of an actual bitmap living in the PixInsight core application. * * %Bitmap provides a comprehensive set of functions and utility routines to * manipulate bitmap images, such as direct pixel access functions, specular * and affine transformations, bitwise logical operations, and high-performance * rendering of images as bitmaps, among many others. * * Along with the Graphics class, %Bitmap can be used for off-screen graphics * output. Graphics offers a thorough collection of painting routines that can * be used to generate sophisticated graphics as bitmaps. * * As we have said, bitmaps are device-independent images in PixInsight. It * must be pointed out that there is no equivalent to a \e device-dependent * bitmap or image in PixInsight: all device dependencies are managed * internally by the PixInsight core application. */ class PCL_CLASS Bitmap : public UIObject { public: /*! * Represents a bitmap pixel format. See the BitmapFormat namespace for * supported values. */ typedef BitmapFormat::value_type pixel_format; /*! * The %display_channel type represents a display channel supported by the * PixInsight core application. Valid channels are defined in the * DisplayChannel namespace. */ typedef DisplayChannel::value_type display_channel; /*! * The %mask_mode type represents a mask rendering mode supported by * the PixInsight core application. Valid mask rendering modes are defined * in the MaskMode namespace. */ typedef MaskMode::value_type mask_mode; /*! * Constructs an empty %Bitmap object. */ Bitmap(); /*! * Constructs a %Bitmap object of the specified \a width and \a height * dimensions, and pixel format \a fmt * * For the sake of performance, bitmap pixel values are not initialized, so * they will contain unpredictable \e garbage values. */ Bitmap( int width, int height, pixel_format fmt = BitmapFormat::ARGB32 ); /*! * Constructs a %Bitmap object from a source image in the XPM format. * * \param xpm Starting address of an XPM image description. * * \b References * * \li http://en.wikipedia.org/wiki/X_PixMap * \li http://www.xfree86.org/current/xpm.pdf */ Bitmap( const char** xpm ); /*! * Constructs a %Bitmap object by loading an embedded resource or disk file. * * \param filePath Path to the source image file or resource. A resource * path begins with the ":/" prefix. For a list of supported * image file formats, see the documentation for the * Load( const String& ) member function. The source file format * is always determined from the specified file extension. * * For more information on embedded resources, see * Bitmap::Bitmap( const char* ). * * In the even of file I/O error, or if the specified file cannot be decoded * and read correctly, this constructor throws an Error exception. */ Bitmap( const String& filePath ); /*! * Constructs a %Bitmap object by loading an embedded resource or disk file. * * \param filePath Path to the source image file or resource. A resource * path begins with the ":/" prefix. For a list of supported * image file formats, see the documentation for the * Load( const String& ) member function. The source file format * is always determined from the specified file extension. * * The PixInsight core application uses the Qt resource system for embedded * images that can be loaded dynamically from .rcc binary files. For * example, the following code snippet loads one of the standard core * application icons: * * \code Bitmap icon( ":/icons/document.png" ); \endcode * * A module can also use the standard ":/@module_root/" prefix to load * module-defined resources. See MetaModule::LoadResource() for a detailed * description. * * In the even of stream I/O error, or if the specified resource or file * cannot be decoded and read correctly, this constructor throws an Error * exception. * * \b References * * \li The Qt Resource System: http://doc.qt.io/qt-5/resources.html */ Bitmap( const char* filePath ); /*! * Constructs a %Bitmap object by loading an embedded resource or disk file. * This constructor is equivalent to Bitmap::Bitmap( const char* ). */ Bitmap( const IsoString& filePath ); /*! * Constructs a %Bitmap object from bitmap data stored in memory. * * \param data Starting address of the source bitmap data block. * * \param size Length of the source data in bytes. * * \param format A nul-terminated character string identifying the format * of the source data. Currently the following formats are * supported by the PixInsight core application: * * * * * * * * * * * * * * * * *
%BMP Windows %Bitmap
%GIF %Graphics Interchange Format
%ICO Windows %Icon Format
%JPG Joint Photographic Experts Group
%WEBP %WebP image format
%MNG Multiple Network %Graphics
%PBM Portable Bitmap
%PNG Portable Network %Graphics
%PPM Portable Pixel Map
%SVG Scalable Vector Graphics
%TIFF Tagged %Image %File Format
%TGA Truevision TGA Format (TARGA)
%XBM X11 Bitmap
%XPM X11 Pixmap
* * The default value (when no format is specified) is SVG. * * \param flags Currently not used. This parameter is reserved for future * extension and its value must be zero (the default value). * * If the \a data address is invalid, or if the data are not valid in the * specified \a format, this constructor throws an Error exception. */ Bitmap( const void* data, size_type size, const char* format = "SVG", uint32 flags = 0 ); /*! * Constructs a %Bitmap object as a subimage of an existing %Bitmap. * * \param bmp Source bitmap. * * \param r Rectangle that defines the source subimage, in source * bitmap coordinates. */ Bitmap( const Bitmap& bmp, const pcl::Rect& r ); /*! * Constructs a %Bitmap object as a subimage of an existing %Bitmap. * * \param bmp Source bitmap. * * \param x0, y0 Coordinates of the upper left corner of the rectangle that * defines the source subimage, in source bitmap coordinates. * * \param x1, y1 Coordinates of the lower right corner of the rectangle * that defines the source subimage, in source bitmap * coordinates. */ Bitmap( const Bitmap& bmp, int x0, int y0, int x1, int y1 ); /*! * Copy constructor. This object will reference the same server-side bitmap * as the specified instance \a b. */ Bitmap( const Bitmap& bmp ) : UIObject( bmp ) { } /*! * Move constructor. */ Bitmap( Bitmap&& x ) : UIObject( std::move( x ) ) { } /*! * Destroys a %Bitmap object. * * The actual bitmap object that this %Bitmap instance refers to lives in * the PixInsight core application, and as such, it will be destroyed and * deallocated (garbage-collected) only when no more references exist to it * in other high-level managed objects, such as other instances of %Bitmap * living in installed modules, or some element of the graphical interface. */ virtual ~Bitmap() { } /*! * Copy assignment operator. Returns a reference to this object. * * Makes this object reference the same server-side bitmap as the specified * instance \a bmp. If the previous bitmap becomes unreferenced, it will be * garbage-collected by the PixInsight core application. */ Bitmap& operator =( const Bitmap& bmp ) { Assign( bmp ); return *this; } /*! * Move assignment operator. Returns a reference to this object. */ Bitmap& operator =( Bitmap&& x ) { Transfer( x ); return *this; } /*! * Returns a reference to a null %Bitmap instance. A null %Bitmap does not * correspond to an existing bitmap in the PixInsight core application. */ static Bitmap& Null(); /*! * Returns the current pixel format for this bitmap. * * Supported pixel format values are enumerated in the BitmapFormat * namespace. */ pixel_format PixelFormat() const; /*! * Sets the pixel format for this bitmap. If necessary, pixel values will * be converted internally to match the specified format. * * Supported pixel format values are enumerated in the BitmapFormat * namespace. */ void SetPixelFormat( pixel_format fmt ); /*! * Renders an image as a bitmap. * * \param image The source image to be rendered. It can be a PCL image of * any supported sample type. * * \param zoom Zoom factor. If zoom == 1, the image will be rendered at * its actual dimensions in pixels. Positive zoom factors are * enlarging ratios; for example, if zoom == 2, the image will * be rendered zoomed 2:1 (twice its actual sizes). Negative * zoom factors are reduction ratios: zoom = -3 means zoomed * 1:3, or one third of the actual image dimensions. * * \param displayChannel See the DisplayChannel enumeration for possible * values. The default mode is DisplayChannel::RGBK, which means * that the image will be rendered in RGB/gray composite mode. * * \param transparency If this parameter is true and the image has one * or more alpha channels, the image will be rendered over a * transparent background and the first alpha channel will * define pixel opacity. If this parameter is false, alpha * channels will not be interpreted as transparency masks. * * \param mask If non-null, this is the address of an image that will be * treated as a mask acting for the source image. Mask pixels * modify the image rendition according to the specified mask * rendering mode (see the maskMode paramter). The mask image * must have the same dimensions as the source image. This * parameter is nullptr by default. * * \param maskMode This parameter defines the mask rendering mode to be * used if a mask image has been specified. See the MaskMode * enumeration for supported values. The default mode is * MaskMode::Default, which corresponds to the red overlay mask * rendering mode. * * \param maskInverted If \a mask is non-null and this parameter is * true, mask pixels will be inverted before rendering them over * source image pixels. * * \param LUT If non-null, this is the address of a look-up * table that will be used to remap bitmap pixel values. * This parameter is nullptr by default. * * \param fastDownsample If this parameter is true, a fast sparse * interpolation algorithm will be used to render the image if a * \a zoom factor less than -2 is specified. Fast subsampling * interpolation is considerably faster than normal (slow) * interpolation, but the generated renditions are less * accurate. In general though, fast interpolation errors are * barely noticeable. This parameter is true by default. * * \param callback If non-null, this is the address of a callback routine * that will be invoked during the bitmap rendition procedure. * If the callback routine returns false, the rendition is * aborted and a null bitmap (Bitmap::Null()) is returned. By * default this parameter is nullptr. * * This is a high-performance routine, implemented with highly optimized * parallel code, that can be used for real-time image visualization. If * allowed through global preferences, it will use all available processors * and processor cores by means of concurrent threads. */ static Bitmap Render( const ImageVariant& image, int zoom = 1, display_channel displayChannel = DisplayChannel::RGBK, bool transparency = true, const ImageVariant* mask = nullptr, mask_mode maskMode = MaskMode::Default, bool maskInverted = false, const uint8** LUT = nullptr, bool fastDownsample = true, bool (*callback)() = nullptr ); /*! * Obtains the dimensions (width, height) of this bitmap in pixels. */ void GetDimensions( int& width, int& height ) const; /*! * Returns the width of this bitmap in pixels. */ int Width() const { int w, dum; GetDimensions( w, dum ); return w; } /*! * Returns the height of this bitmap in pixels. */ int Height() const { int dum, h; GetDimensions( dum, h ); return h; } /*! * Returns the bounding rectangle of this bitmap. * * The upper-left corner of the returned rectangle is always at (0,0). The * width and height of the returned rectangle are the bitmap dimensions. */ pcl::Rect Bounds() const { int w, h; GetDimensions( w, h ); return pcl::Rect( w, h ); } /*! * Returns true iff this bitmap is empty. An empty bitmap has zero dimensions * and does not contain any image. */ bool IsEmpty() const; /*! * Returns true iff this bitmap contains an image, that is, if it is not an * empty bitmap. * * This is a convenience operator that simply returns !IsEmpty(). */ operator bool() const { return !IsEmpty(); } /*! * \defgroup bitmap_pixel_access Bitmap Pixel Access Functions */ /*! * Returns the value of a bitmap pixel. * * \param x,y Bitmap coordinates of the pixel to read. Pixel coordinates * can vary in the range from (0,0) to (Width()-1, Height()-1). * * \ingroup bitmap_pixel_access */ RGBA Pixel( int x, int y ) const; /*! * Returns the value of a bitmap pixel. * * \param p A Point object whose coordinates identify the pixel to read. * Pixel coordinates can vary in the range from (0,0) to * (Width()-1, Height()-1). * * \ingroup bitmap_pixel_access */ RGBA Pixel( const pcl::Point& p ) const { return Pixel( p.x, p.y ); } /*! * Sets the value of a bitmap pixel. * * \param x,y Bitmap coordinates of the pixel to write. Pixel coordinates * can vary in the range from (0,0) to (Width()-1, Height()-1). * * \param v 32-bit pixel value encoded in the AARRGGBB format: AA is the * alpha (transparency) value, RR is the red component, GG is * green and BB is blue. Each element is an 8-bit value. * * \ingroup bitmap_pixel_access */ void SetPixel( int x, int y, RGBA v ); /*! * Sets the value of a bitmap pixel. * * \param p A Point object whose coordinates identify the pixel to write. * Pixel coordinates can vary in the range from (0,0) to * (Width()-1, Height()-1). * * \param v 32-bit pixel value encoded in the AARRGGBB format: AA is the * alpha (transparency) value, RR is the red component, GG is * green and BB is blue. Each element is an 8-bit value. * * \ingroup bitmap_pixel_access */ void SetPixel( const pcl::Point& p, RGBA v ) { SetPixel( p.x, p.y, v ); } /*! * Returns the (constant) starting address of a row of pixels in this * bitmap. * * \param y Vertical coordinate of the row of pixels. Vertical * coordinates can vary in the range from 0 to Height()-1. * * \ingroup bitmap_pixel_access */ const RGBA* ScanLine( int y ) const; /*! * Returns the starting address of a row of pixels in this bitmap. * * \param y Vertical coordinate of the row of pixels. Vertical * coordinates can vary in the range from 0 to Height()-1. * * The returned address can be used to modify pixel values. * * \ingroup bitmap_pixel_access */ RGBA* ScanLine( int y ); /*! * \defgroup bitmap_specular_transformations Bitmap Specular Transformations */ /*! * Returns a mirrored duplicate of this bitmap. The original (this) bitmap * is not modified. * * \ingroup bitmap_specular_transformations */ Bitmap Mirrored() const; /*! * Returns a duplicate of this bitmap, mirrored horizontally. The original * (this) bitmap is not modified. * * \ingroup bitmap_specular_transformations */ Bitmap MirroredHorizontally() const; /*! * Returns a duplicate of this bitmap, mirrored vertically. The original * (this) bitmap is not modified. * * \ingroup bitmap_specular_transformations */ Bitmap MirroredVertically() const; /*! * \defgroup bitmap_affine_transformations Bitmap Affine Transformations */ /*! * Returns a scaled duplicate of this bitmap. * * \param sx,sy Scaling factors in the X and Y axes. * * \param precise If this parameter is true, the scaled bitmap will be * generated using a precise, smooth interpolation algorithm. * This parameter is true by default. * * \ingroup bitmap_affine_transformations */ Bitmap Scaled( double sx, double sy, bool precise = true ) const; /*! * Returns a scaled duplicate of this bitmap. * * \param sxy Scaling factor applied to both X and Y axes. * * \param precise If this parameter is true, the scaled bitmap will be * generated using a precise, smooth interpolation algorithm. * This parameter is true by default. * * \ingroup bitmap_affine_transformations */ Bitmap Scaled( double sxy, bool precise = true ) const; /*! * Returns a scaled duplicate of this bitmap, with its width equal to a * prescribed value in pixels. * * \param width Width in pixels of the returned bitmap. If this parameter * is zero, an empty bitmap will be returned. * * \param precise If this parameter is true, the scaled bitmap will be * generated using a precise, smooth interpolation algorithm. * This parameter is true by default. * * \ingroup bitmap_affine_transformations */ Bitmap ScaledToWidth( int width, bool precise = true ) const; /*! * Returns a scaled duplicate of this bitmap, with its height equal to a * prescribed value in pixels. * * \param height Height in pixels of the returned bitmap. If this parameter * is zero, an empty bitmap will be returned. * * \param precise If this parameter is true, the scaled bitmap will be * generated using a precise, smooth interpolation algorithm. * This parameter is true by default. * * \ingroup bitmap_affine_transformations */ Bitmap ScaledToHeight( int height, bool precise = true ) const; /*! * Returns a scaled duplicate of this bitmap, with its width and height * equal to prescribed values in pixels. * * \param width, height Width and height in pixels of the returned * bitmap. If one or both of these parameters are zero, an * empty bitmap will be returned. * * \param precise If this parameter is true, the scaled bitmap will be * generated using a precise, smooth interpolation algorithm. * This parameter is true by default. * * \ingroup bitmap_affine_transformations */ Bitmap ScaledToSize( int width, int height, bool precise = true ) const; /*! * Returns a rotated duplicate of this bitmap. * * \param angle %Rotation angle in radians. * * \param precise If this parameter is true, the rotated bitmap will be * generated using a precise, smooth interpolation algorithm. * This parameter is true by default. * * \ingroup bitmap_affine_transformations */ Bitmap Rotated( double angle, bool precise = true ) const; /*! * \defgroup bitmap_file_io Bitmap File I/O Routines */ /*! * Loads a disk image file in this bitmap. * * \param filePath %File path to the input image file. * * The input file format is always determined by the specified file * extension (in \a filePath). Supported input formats: * * * * * * * * * * * * * * * * *
%BMP Windows %Bitmap (.bmp)
%GIF %Graphics Interchange Format (.gif) (read-only)
%ICO Windows %Icon Format (.ico)
%JPEG Joint Photographic Experts Group (.jpg, .jpeg)
%WEBP %WebP image format (.webp)
%MNG Multiple Network %Graphics (.mng) (read-only)
%PBM Portable BitMap (.pbm) (read-only)
%PNG Portable Network %Graphics (.png)
%PPM Portable Pixel Map (.ppm)
%SVG Scalable Vector Graphics (.svg) (read-only)
%TIFF Tagged %Image %File Format (.tif, .tiff).
%TGA Truevision TGA Format (TARGA) (.tga, .tpic).
%XBM X BitMap (.xbm)
%XPM X PixMap (.xpm)
* * In the even of file I/O error, or if the specified file cannot be decoded * and loaded correctly, this member function throws an Error exception. * * \ingroup bitmap_file_io */ void Load( const String& filePath ); /*! * Saves this bitmap to a disk image file. * * \param filePath %File path to the output image file. * * \param quality Image quality for lossy compression in the range from 0 * (lowest quality) to 100 (highest quality). Currently, this * parameter is ignored if the output file is not in one of the * %JPEG or %WebP formats. If this parameter is < 0, a default, * format-dependent quality will be used. * * The output file format is always determined by the specified file * extension (in \a filePath). Supported output formats include: * * * * * * * * * * * *
%BMP Windows %Bitmap (.bmp)
%ICO Windows %Icon Format (.ico)
%JPEG Joint Photographic Experts Group (.jpg, .jpeg)
%WEBP %WebP image format (.webp)
%PNG Portable Network %Graphics (.png)
%PPM Portable Pixel Map (.ppm)
%TIFF Tagged %Image %File Format (.tif, .tiff).
%XBM X BitMap (.xbm)
%XPM X PixMap (.xpm)
* * In the even of file I/O error, or if the specified file cannot be encoded * and written correctly, this member function throws an Error exception. * * \ingroup bitmap_file_io */ void Save( const String& filePath, int quality = -1 ) const; /*! * Loads this bitmap from data stored in memory. * * \param data Starting address of the source bitmap data block. * * \param size Length of the source data in bytes. * * \param format A nul-terminated character string identifying the format * of the source data. Currently the only supported format is * Scalable Vector Graphics (SVG), and this is also the * default value of this parameter ("SVG"). * * \param flags Currently not used. This parameter is reserved for future * extension and its value must be zero (the default value). * * If the \a data address is invalid, or if the data are not valid in the * specified \a format, this member function throws an Error exception. */ void Load( const void* data, size_type size, const char* format = "SVG", uint32 flags = 0 ); /*! * Returns a subimage of this bitmap. * * \param x0, y0 Coordinates of the upper left corner of the source * rectangular region. * * \param x1, y1 Coordinates of the lower right corner of the source * rectangular region. * * The rectangular region defines the size and position of the subimage that * is extracted and returned as a new %Bitmap object. */ Bitmap Subimage( int x0, int y0, int x1, int y1 ) const; /*! * Returns a subimage of this bitmap. * * \param r A Rect object defining subimage boundaries. * * The rectangular area defines the size and position of the subimage that * is extracted and returned as a new %Bitmap object. */ Bitmap Subimage( const pcl::Rect& r ) const { return Subimage( r.x0, r.y0, r.x1, r.y1 ); } /*! * \defgroup bitmap_bitwise_ops Bitmap Bitwise Logical Operations */ /*! * Copies a region of a source bitmap to the specified location on this * bitmap. * * \param p Position of the upper left corner of the target rectangle on * this bitmap. * * \param src Source bitmap, whose pixels will be copied to this bitmap. * * \param r Defines the rectangular area that will be copied, in source * bitmap coordinates. * * Target pixels on this bitmap are replaced with pixels read from the * source bitmap \a src. Source pixels falling outside the boundaries of * this bitmap are ignored. * * \ingroup bitmap_bitwise_ops */ void Copy( const pcl::Point& p, const Bitmap& src, const pcl::Rect& r ); /*! * Copies all pixels from a source bitmap to the specified location on this * bitmap. * * \param p Position of the upper left corner of the target rectangle on * this bitmap. * * \param src Source bitmap, whose pixels will be copied to this bitmap. * * Target pixels on this bitmap are replaced with pixels read from the * source bitmap \a src. Source pixels falling outside the boundaries of * this bitmap are ignored. * * This function is equivalent to: * * Copy( p, src, src.Bounds() ); * * \ingroup bitmap_bitwise_ops */ void Copy( const pcl::Point& p, const Bitmap& src ) { Copy( p, src, src.Bounds() ); } /*! * Copies all pixels from a source bitmap to this bitmap. * * \param src Source bitmap, whose pixels will be copied to this bitmap. * * Target pixels on this bitmap are replaced with pixels read from the * source bitmap \a src. Pixels are copied at the upper left corner of this * image (0,0). Source pixels falling outside the boundaries of this bitmap * are ignored. * * This function is equivalent to: * * Copy( pcl::Point( 0, 0 ), src ); * * \ingroup bitmap_bitwise_ops */ void Copy( const Bitmap& src ) { Copy( pcl::Point( 0 ), src ); } /*! * Fills a rectangular region of this bitmap with a constant value. * * \param rect Rectangular region to be filled. * \param fillWith Pixel value to fill with. * * \ingroup bitmap_bitwise_ops */ void Fill( const pcl::Rect& rect, RGBA fillWith ); /*! * Fills the entire bitmap with a constant value \a fillWith. This * function is equivalent to: * * Fill( Bounds(), fillWith ); * * \ingroup bitmap_bitwise_ops */ void Fill( RGBA fillWith ) { Fill( Bounds(), fillWith ); } /*! * Replaces each pixel in a rectangular region of this bitmap with the * result of the bitwise inclusive OR operation between its current value * and a specified constant value. * * \param rect Rectangular region to be operated. * \param orWith Value to be ORed with current pixel values. * * \ingroup bitmap_bitwise_ops */ void Or( const pcl::Rect& rect, RGBA orWith ); /*! * Replaces each pixel in this bitmap with the result of the bitwise * inclusive OR operation between its current value and a specified constant * value \a andWith. * * This function is equivalent to: * * Or( Bounds(), orWith ); * * \ingroup bitmap_bitwise_ops */ void Or( RGBA orWith ) { Or( Bounds(), orWith ); } /*! * Replaces a rectangular region of this bitmap with the bitwise inclusive * OR operation between its current pixel values and the pixels of a * corresponding region of a source bitmap. * * \param p Position of the upper left corner of the target rectangle on * this bitmap. * * \param src Source bitmap whose pixels will be ORed with this bitmap. * * \param r Defines the rectangular area that will be operated, in source * bitmap coordinates. * * Target pixels on this bitmap are replaced with the result of the bitwise * OR operation with the corresponding pixels read from the source bitmap * \a src. Source pixels falling outside the boundaries of this bitmap are * ignored. * * \ingroup bitmap_bitwise_ops */ void Or( const pcl::Point& p, const Bitmap& src, const pcl::Rect& r ); /*! * Replaces a rectangular region of this bitmap with the bitwise inclusive * OR operation between its current pixel values and the corresponding * pixels of a source bitmap. * * \param p Position of the upper left corner of the target rectangle on * this bitmap. * * \param src Source bitmap whose pixels will be ORed with this bitmap. * * Target pixels on this bitmap are replaced with the result of the bitwise * OR operation with the corresponding pixels read from the source bitmap * \a src. Source pixels falling outside the boundaries of this bitmap are * ignored. * * This function is equivalent to: * * Or( p, src, src.Bounds() ); * * \ingroup bitmap_bitwise_ops */ void Or( const pcl::Point& p, const Bitmap& src ) { Or( p, src, src.Bounds() ); } /*! * Replaces all pixels in this bitmap with the bitwise inclusive OR * operation between their current values and the pixels of a source bitmap * \a src. This function is equivalent to: * * Or( Point( 0, 0 ), src ); * * \ingroup bitmap_bitwise_ops */ void Or( const Bitmap& src ) { Or( pcl::Point( 0 ), src ); } /*! * Replaces each pixel in a rectangular region of this bitmap with the * result of the bitwise AND operation between its current value and a * specified constant value. * * \param rect Rectangular region to be operated. * \param andWith Value to be ANDed with current pixel values. * * \ingroup bitmap_bitwise_ops */ void And( const pcl::Rect& rect, RGBA andWith ); /*! * Replaces each pixel in this bitmap with the result of the bitwise * AND operation between its current value and a specified constant value * \a andWith. * * This function is equivalent to: * * And( Bounds(), andWith ); * * \ingroup bitmap_bitwise_ops */ void And( RGBA andWith ) { And( Bounds(), andWith ); } /*! * Replaces a rectangular region of this bitmap with the bitwise AND * operation between its current pixel values and the pixels of a * corresponding region of a source bitmap. * * \param p Position of the upper left corner of the target rectangle on * this bitmap. * * \param src Source bitmap whose pixels will be ANDed with this bitmap. * * \param r Defines the rectangular area that will be operated, in source * bitmap coordinates. * * Target pixels on this bitmap are replaced with the result of the bitwise * AND operation with the corresponding pixels read from the source bitmap * \a src. Source pixels falling outside the boundaries of this bitmap are * ignored. * * \ingroup bitmap_bitwise_ops */ void And( const pcl::Point& p, const Bitmap& src, const pcl::Rect& r ); /*! * Replaces a rectangular region of this bitmap with the bitwise AND * operation between its current pixel values and the corresponding pixels * of a source bitmap. * * \param p Position of the upper left corner of the target rectangle on * this bitmap. * * \param src Source bitmap whose pixels will be ANDed with this bitmap. * * Target pixels on this bitmap are replaced with the result of the bitwise * AND operation with the corresponding pixels read from the source bitmap * \a src. Source pixels falling outside the boundaries of this bitmap are * ignored. * * This function is equivalent to: * * And( p, src, src.Bounds() ); * * \ingroup bitmap_bitwise_ops */ void And( const pcl::Point& p, const Bitmap& src ) { And( p, src, src.Bounds() ); } /*! * Replaces all pixels in this bitmap with the bitwise AND operation between * their current values and the pixels of a source bitmap \a src. This * function is equivalent to: * * And( Point( 0, 0 ), src ); * * \ingroup bitmap_bitwise_ops */ void And( const Bitmap& src ) { And( pcl::Point( 0 ), src ); } /*! * Replaces each pixel in a rectangular region of this bitmap with the * result of the bitwise exclusive OR (XOR) operation between its current * value and a specified constant value. * * \param rect Rectangular region to be operated. * \param xorWith Value to be XORed with current pixel values. * * \ingroup bitmap_bitwise_ops */ void Xor( const pcl::Rect& rect, RGBA xorWith ); /*! * Replaces each pixel in this bitmap with the result of the bitwise * exclusive OR (XOR) operation between its current value and a specified * constant value \a xorWith. * * This function is equivalent to: * * Xor( Bounds(), xorWith ); * * \ingroup bitmap_bitwise_ops */ void Xor( RGBA xorWith ) { Xor( Bounds(), xorWith ); } /*! * Replaces a rectangular region of this bitmap with the bitwise exclusive * OR (XOR) operation between its current pixel values and the pixels of a * corresponding region of a source bitmap. * * \param p Position of the upper left corner of the target rectangle on * this bitmap. * * \param src Source bitmap whose pixels will be XORed with this bitmap. * * \param r Defines the rectangular area that will be operated, in source * bitmap coordinates. * * Target pixels on this bitmap are replaced with the result of the XOR * operation with the corresponding pixels read from the source bitmap * \a src. Source pixels falling outside the boundaries of this bitmap are * ignored. * * \ingroup bitmap_bitwise_ops */ void Xor( const pcl::Point& p, const Bitmap& src, const pcl::Rect& r ); /*! * Replaces a rectangular region of this bitmap with the bitwise exclusive * OR (XOR) operation between its current pixel values and the corresponding * pixels of a source bitmap. * * \param p Position of the upper left corner of the target rectangle on * this bitmap. * * \param src Source bitmap whose pixels will be XORed with this bitmap. * * Target pixels on this bitmap are replaced with the result of the * exclusive OR (XOR) operation with the corresponding pixels read from the * source bitmap \a src. Source pixels falling outside the boundaries of * this bitmap are ignored. * * This function is equivalent to: * * Xor( p, src, src.Bounds() ); * * \ingroup bitmap_bitwise_ops */ void Xor( const pcl::Point& p, const Bitmap& src ) { Xor( p, src, src.Bounds() ); } /*! * Replaces all pixels in this bitmap with the bitwise exclusive OR (XOR) * operation between their current values and the pixels of a source bitmap * \a src. This function is equivalent to: * * Xor( Point( 0, 0 ), src ); * * \ingroup bitmap_bitwise_ops */ void Xor( const Bitmap& src ) { Xor( pcl::Point( 0 ), src ); } /*! * Replaces the pixels pertaining to a rectangle defined on this bitmap with * the bitwise exclusive OR (XOR) operation between their current values and * a specified constant value. * * \param rect Rectangle that will be operated. * * \param xorWith Value to be XORed with current pixel values. * * This function does not operate on a rectangular region; only the \e sides * of the specified rectangle are XORed: two one-pixel columns and two * one-pixel rows. * * \ingroup bitmap_bitwise_ops */ void XorRect( const pcl::Rect& rect, RGBA xorWith ); /*! * Replaces the pixels pertaining to the bounding rectangle of this bitmap * with the bitwise exclusive OR (XOR) operation between their current * values and a specified constant value. * * \param xorWith Value to be XORed with current pixel values. * * This function is equivalent to: * * XorRect( Bounds(), xorWith ); * * \ingroup bitmap_bitwise_ops */ void XorRect( RGBA xorWith ) { XorRect( Bounds(), xorWith ); } /*! * Inverts a rectangular region of this bitmap. * * \param rect Rectangular region to be inverted. * * This function does not invert alpha pixel components, but just color * components. It is equivalent to: * * Xor( rect, 0x00ffffff ); * * \ingroup bitmap_bitwise_ops */ void Invert( const pcl::Rect& rect ) { Xor( rect, 0x00ffffff ); } /*! * Inverts all pixels of this bitmap. * * This function does not invert alpha pixel components, but just color * components. It is equivalent to: * * Invert( Bounds() ); * * \ingroup bitmap_bitwise_ops */ void Invert() { Invert( Bounds() ); } /*! * Inverts the pixels pertaining to a rectangle \a rect defined on this * bitmap. * * This function does not invert alpha pixel components, but just color * components. It is equivalent to: * * XorRect( rect, 0x00ffffff ); * * \ingroup bitmap_bitwise_ops */ void InvertRect( const pcl::Rect& rect ) { XorRect( rect, 0x00ffffff ); } /*! * Inverts the pixels pertaining to the bounding rectangle of this bitmap. * * This function does not invert alpha pixel components, but just color * components. It is equivalent to: * * InvertRect( Bounds() ); * * \ingroup bitmap_bitwise_ops */ void InvertRect() { InvertRect( Bounds() ); } /*! * \defgroup bitmap_color_replacement Bitmap Color Replacement Functions */ /*! * Replaces all occurrences of a specified pixel value in a rectangular * region of this bitmap with a new value. * * \param rect Rectangular region. * \param replaceThis Pixel value to be replaced. * \param replaceWith New pixel value for replacement. * * \ingroup bitmap_color_replacement */ void ReplaceColor( const pcl::Rect& rect, RGBA replaceThis, RGBA replaceWith ); /*! * Replaces all occurrences of a specified pixel value in this bitmap with a * new value. * * \param replaceThis Pixel value to be replaced. * \param replaceWith New pixel value for replacement. * * This function is equivalent to: * * ReplaceColor( Bounds(), replaceThis, replaceWith ); * * \ingroup bitmap_color_replacement */ void ReplaceColor( RGBA replaceThis, RGBA replaceWith ) { ReplaceColor( Bounds(), replaceThis, replaceWith ); } /*! * Replaces the alpha (transparency) components of all pixels in a * rectangular region of this bitmap with a new alpha value. * * \param rect Rectangular region. * \param newAlpha New alpha (transparency) value in the range [0,255]. * * \ingroup bitmap_color_replacement */ void SetAlpha( const pcl::Rect& rect, uint8 newAlpha ); /*! * Replaces the alpha (transparency) components of all pixels in this bitmap * with a new alpha value. * * \param newAlpha New alpha (transparency) value in the range [0,255]. * * This function is equivalent to: * * SetAlpha( Bounds(), newAlpha ); * * \ingroup bitmap_color_replacement */ void SetAlpha( uint8 newAlpha ) { SetAlpha( Bounds(), newAlpha ); } /*! * Returns the ratio between output device pixels and pixels of this * device-independent bitmap. See the SetPhysicalPixelRatio() member * function for a detailed description. * * \ingroup ui_scaling_functions * \sa SetPhysicalPixelRatio() */ double PhysicalPixelRatio() const; /*! * Sets the ratio between output device pixels and pixels of this * device-independent bitmap. This ratio is used as a scaling factor by * core bitmap rendering routines to reproduce bitmaps on high-dpi screens * and other high-density graphics output devices. * * The specified \e ratio must be greater than or equal to one. On macOS * with Retina monitors working in high-dpi modes, this function can be used * to ensure that a bitmap will be reproduced as a high-resolution image by * setting its output pixel ratio to 2.0. In such case the bitmap will be * drawn on the screen with one half its actual pixel dimensions in logical * pixels, using the native physical monitor resoluton. On other platforms * such as X11 (Linux and FreeBSD) and Windows, where no automatic display * scaling is performed, the physical pixel ratio of a bitmap is ignored. * * \ingroup ui_scaling_functions * \sa PhysicalPixelRatio() */ void SetPhysicalPixelRatio( double ratio ); /*! * Renders an SVG document file as a raster image into a new %Bitmap object. * * \param filePath Path to an existing file in the local file system, * which must store a valid SVG document representing the * image to be rendered. The SVG source code must be * encoded in UTF-8. * * \param width,height The width and height in pixels of the image where * the SVG rendition will be generated. If a dimension is * ≤ 0, the rendition will use the corresponding * dimension specified by the SVG document: either viewBox * coordinates, if available, or the width and height * attributes of the root svg element. * * \param options Rendering options. See the SVGRenderOption namespace * for possible values. * * Automatic Resource Location * * This function can load SVG documents from arbitrary locations on the * local file system. However, modules typically install their process and * interface icons on the /rsc/icons/module directory under the local * PixInsight installation. A module can specify the "@module_icons_dir/" * prefix in the \a filePath argument to this function to let the PixInsight * core application load the corresponding SVG document from the appropriate * standard distribution directory automatically. For example, suppose that * this function is invoked by a "Foo" module as follows: * * \code * Bitmap RenderSpecialIcon() * { * return Bitmap::FromSVGFile( "@module_icons_dir/special/icon.svg" ); * } * \endcode * * Then the core application will attempt to load the following SVG file: * * <install-dir>/rsc/icons/module/Foo/special/icon.svg * * where <install-dir> is the local directory where the running * PixInsight core application is installed. * * \sa FromSVG() */ static Bitmap FromSVGFile( const String& filePath, int width = 0, int height = 0, SVGRenderOptions options = SVGRenderOption::Default ); /*! * Renders an SVG document as a raster image into a new %Bitmap object. * * \param filePath The source code of a valid SVG document representing * the image to be rendered, encoded in UTF-8. * * \param width,height The width and height in pixels of the image where * the SVG rendition will be generated. If a dimension is * ≤ 0, the rendition will use the corresponding * dimension specified by the SVG document: either viewBox * coordinates, if available, or the width and height * attributes of the root svg element. * * \param options Rendering options. See the SVGRenderOption namespace * for possible values. * * \sa FromSVGFile() */ static Bitmap FromSVG( const IsoString& svgSource, int width = 0, int height = 0, SVGRenderOptions options = SVGRenderOption::Default ); private: Bitmap( void* h ) : UIObject( h ) { } void* CloneHandle() const override; friend class GraphicsContextBase; friend class Graphics; friend class VectorGraphics; friend class Action; friend class Brush; friend class Cursor; friend class Button; friend class PushButton; friend class ToolButton; friend class BitmapBox; friend class TabBox; friend class ComboBox; friend class TreeBox; friend class ImageView; friend class ImageWindow; friend class Process; friend class FileFormat; }; // ---------------------------------------------------------------------------- #endif // __PCL_BUILDING_PIXINSIGHT_APPLICATION } // pcl #endif // __PCL_Bitmap_h // ---------------------------------------------------------------------------- // EOF pcl/Bitmap.h - Released 2022-03-12T18:59:29Z