[]
        
(Showing Draft Content)

GrapeCity.Documents.Imaging.Windows.GcWicBitmap

Class GcWicBitmap

Namespace
GrapeCity.Documents.Imaging.Windows
Assembly
GcDocs.Imaging.Windows.dll

Represents a bitmap based on Windows Imaging Component.

public class GcWicBitmap : IImage, IDisposable
Inheritance
object
GcWicBitmap
Implements
System.IDisposable
Inherited Members
object.ToString()
object.Equals(object)
object.Equals(object, object)
object.ReferenceEquals(object, object)
object.GetHashCode()
object.GetType()
object.MemberwiseClone()

Constructors

GcWicBitmap()

Initializes an instance of the GcWicBitmap class.

public GcWicBitmap()

GcWicBitmap(Image, Rectangle?)

Initializes a new instance of the GcWicBitmap class.

public GcWicBitmap(Image image, Rectangle? imageRect = null)

Parameters

image Image

Image used as the source of image data.

imageRect System.Drawing.Rectangle?

Clipping rectangle of the image to be loaded.

GcWicBitmap(ImagingFactory)

Initializes a new instance of the GcWicBitmap class.

public GcWicBitmap(ImagingFactory imagingFactory)

Parameters

imagingFactory ImagingFactory

The existing imaging factory, to avoid duplicating factories.

GcWicBitmap(GcBitmap, ImagingFactory)

Initializes a new instance of the GcWicBitmap class from an instance of GcBitmap.

If the source image is not opaque, the color channels must be premultiplied with the alpha channel.

public GcWicBitmap(GcBitmap bitmap, ImagingFactory imagingFactory = null)

Parameters

bitmap GcBitmap

The source GcBitmap.

imagingFactory ImagingFactory

The existing imaging factory, to avoid duplicating factories.

See Also

GcWicBitmap(byte[], int, Rectangle?)

Initializes a new instance of the GcWicBitmap class.

public GcWicBitmap(byte[] bytes, int frameIndex = 0, Rectangle? imageRect = null)

Parameters

bytes byte[]

The image data. JPEG, PNG, GIF, BMP, TIFF, ICO, JPEG XR formats are supported.

frameIndex int

Index of an image frame to read, pass 0 for image formats not supporting multiple frames.

imageRect System.Drawing.Rectangle?

Clipping rectangle of the image to be loaded.

GcWicBitmap(int, int, bool, float, float)

Initializes a new instance of the GcWicBitmap class and creates the image.

The image content is not initialized and can contain any random data.

public GcWicBitmap(int pixelWidth, int pixelHeight, bool opaque, float dpiX = 96, float dpiY = 96)

Parameters

pixelWidth int

The width of the image, in pixels.

pixelHeight int

The height of the image, in pixels.

opaque bool

Indicates whether the alpha channel should be ignored.

dpiX float

The horizontal dpi of the image.

dpiY float

The vertical dpi of the image.

GcWicBitmap(Stream, int, Rectangle?)

Initializes a new instance of the GcWicBitmap class.

public GcWicBitmap(Stream stream, int frameIndex = 0, Rectangle? imageRect = null)

Parameters

stream System.IO.Stream

The source stream. JPEG, PNG, GIF, BMP, TIFF, ICO, JPEG XR formats are supported.

frameIndex int

Index of an image frame to read, pass 0 for image formats not supporting multiple frames.

imageRect System.Drawing.Rectangle?

Clipping rectangle of the image to be loaded.

GcWicBitmap(string, int, Rectangle?)

Initializes a new instance of the GcWicBitmap class.

public GcWicBitmap(string path, int frameIndex = 0, Rectangle? imageRect = null)

Parameters

path string

The file path to the image. JPEG, PNG, GIF, BMP, TIFF, ICO, JPEG XR formats are supported.

frameIndex int

Index of an image frame to read, pass 0 for image formats not supporting multiple frames.

imageRect System.Drawing.Rectangle?

Clipping rectangle of the image to be loaded.

Properties

Brush

Gets an instance of the SolidColorBrush class.

The brush becomes available after executing the EnsureRenderTargetCreated() method.

public SolidColorBrush Brush { get; }

Property Value

SolidColorBrush

D2DFactory

Gets an instance of the Factory1 class.

The factory becomes available after executing the EnsureRenderTargetCreated() method.

public Factory1 D2DFactory { get; }

Property Value

Factory1

DpiX

Gets the x-axis dpi resolution.

public float DpiX { get; }

Property Value

float

DpiY

Gets the y-axis dpi resolution.

public float DpiY { get; }

Property Value

float

DWFactory

Gets an instance of the Factory1 class.

The factory becomes available after initializing the font cache (see the SetFontCache(FontCache) method).

public Factory1 DWFactory { get; }

Property Value

Factory1

Graphics

Gets an instance of the GcWicBitmapGraphics class.

The Graphics becomes available after executing the CreateGraphics(Color?) method.

public GcWicBitmapGraphics Graphics { get; }

Property Value

GcWicBitmapGraphics

GraphicsSupported

Gets a value indicating if GcWicBitmap supports the CreateGraphics(Color?) method on the current platform.

public static bool GraphicsSupported { get; }

Property Value

bool

HasImage

Gets a value indicating whether the underlying image exists (has been loaded or created). If this property is false, call Load() or CreateImage() to load or create the underlying image. Calling any other method will throw an exception unless this property is true.

public bool HasImage { get; }

Property Value

bool
See Also

Height

Gets the height of the image, in DIPs.

public float Height { get; }

Property Value

float

ImagingFactory

Gets an instance of the ImagingFactory class.

public ImagingFactory ImagingFactory { get; }

Property Value

ImagingFactory

IsDisposed

Gets a value indicating whether the GcWicBitmap has been disposed of.

public bool IsDisposed { get; }

Property Value

bool

IsSupported

Gets a value indicating if GcWicBitmap is available on the current platform.

Make sure that "Thread.CurrentThread.SetApartmentState(ApartmentState.MTA)" is executed at the beginning of the Program.Main() method.

public static bool IsSupported { get; }

Property Value

bool

NativeBitmap

Gets the internal image that is an IWICBitmap.

public Bitmap NativeBitmap { get; }

Property Value

Bitmap

PixelFormat

Gets the pixel format of the image.

public WicPixelFormat PixelFormat { get; }

Property Value

WicPixelFormat

PixelHeight

Gets the pixel height of the image.

public int PixelHeight { get; }

Property Value

int

PixelWidth

Gets the pixel width of the image.

public int PixelWidth { get; }

Property Value

int

RenderTarget

Gets an instance of the RenderTarget class.

The render target becomes available after executing the EnsureRenderTargetCreated() method.

public RenderTarget RenderTarget { get; }

Property Value

RenderTarget

Width

Gets the width of the image, in DIPs.

public float Width { get; }

Property Value

float

Methods

ApplyLicenseKey(string)

Applies a license key to an instance of GcWicBitmap.

public void ApplyLicenseKey(string key)

Parameters

key string

The license key to set.

BitsPerPixel(WicPixelFormat)

Returns the number of bits-per-pixel (bpp) for the given value of the PixelFormat enumeration.

public static int BitsPerPixel(WicPixelFormat pixelFormat)

Parameters

pixelFormat WicPixelFormat

The PixelFormat enumeration value.

Returns

int

CanConvertTo(WicPixelFormat)

Determines if the current pixel format can be converted to the destination pixel format.

public bool CanConvertTo(WicPixelFormat pixelFormat)

Parameters

pixelFormat WicPixelFormat

The destionation pixel format.

Returns

bool

CreateGraphics(Color?)

Creates an instance of the GcWicBitmapGraphics class.

public GcWicBitmapGraphics CreateGraphics(Color? backColor = null)

Parameters

backColor System.Drawing.Color?

If not null, specifies the color to clear the image with.

Returns

GcWicBitmapGraphics

A new instance of GcWicBitmapGraphics.

CreateImage(int, int, bool, float, float)

Creates the image of the given size and resolution.

The content is not initialized and can contain any random data.

public void CreateImage(int pixelWidth, int pixelHeight, bool opaque, float dpiX = 96, float dpiY = 96)

Parameters

pixelWidth int

The width of the image, in pixels.

pixelHeight int

The height of the image, in pixels.

opaque bool

Indicates if the alpha channel should be ignored.

dpiX float

The horizontal dpi of the image.

dpiY float

The vertical dpi of the image.

CreatePaletteFromBitmap(int, bool)

Creates a palette using a computed optimized values based on the bitmap.

public GcWicBitmap.Palette CreatePaletteFromBitmap(int colorCount, bool addTransparentColor)

Parameters

colorCount int

The number of colors to initialize the palette with.

addTransparentColor bool

A value to indicate whether to add a transparent color.

Returns

GcWicBitmap.Palette

Remarks

The resulting palette contains the specified number of colors which best represent the colors present in the bitmap. The algorithm operates on the opaque RGB color value of each pixel in the reference bitmap and hence ignores any alpha values. If a transparent color is required, set the addTransparentColor parameter to true and one fewer optimized color will be computed, reducing the colorCount, and a fully transparent color entry will be added.

CreatePredefinedPalette(WicPaletteType, bool)

Creates one of the pre-defined palettes specified by PaletteType and optionally adds a transparent color.

public GcWicBitmap.Palette CreatePredefinedPalette(WicPaletteType paletteType, bool addTransparentColor)

Parameters

paletteType WicPaletteType

The desired pre-defined palette type.

addTransparentColor bool

The optional transparent color to add to the palette. If no transparent color is needed, use false. When initializing to a grayscale or black and white palette, set this parameter to false.

Returns

GcWicBitmap.Palette

Remarks

For palettes with less than 256 entries, the transparent entry is added to the end of the palette (that is, a 16-color palette becomes a 17-color palette). For palettes with 256 colors, the transparent palette entry will replace the last entry in the pre-defined palette.

DiscardImage()

Releases the internal image and clears all metadata.

public void DiscardImage()

Dispose()

Clean up any resources being used.

public void Dispose()

Dispose(bool)

Performs cleanup operations on managed and unmanaged resources.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

EnsureRenderTargetCreated()

Creates a render target for the internal WIC image, if it has not been created yet.

public RenderTarget EnsureRenderTargetCreated()

Returns

RenderTarget

ExportFragment(GcBitmap, int, int, Rectangle)

Copies a fragment of the image to the specified GcBitmap object.

public void ExportFragment(GcBitmap dstBitmap, int xDst, int yDst, Rectangle srcRect)

Parameters

dstBitmap GcBitmap

The destination GcBitmap object.

xDst int

The x-coordinate, in pixels, of the upper-left corner of the destination rectangle.

yDst int

The y-coordinate, in pixels, of the upper-left corner of the destination rectangle.

srcRect System.Drawing.Rectangle

The source rectangle within the image.

ExportFragment(IntPtr, Rectangle)

Copies a fragment of the image to the unmanaged block of memory.

public int ExportFragment(IntPtr dstPtr, Rectangle srcRect)

Parameters

dstPtr System.IntPtr

The pointer to the unmanaged block of memory or IntPtr.Zero.

srcRect System.Drawing.Rectangle

The source rectangle within the image.

Returns

int

Returns the number of bytes in the requested fragment of the image.

~GcWicBitmap()

Performs cleanup operations on unmanaged resources.

protected ~GcWicBitmap()

GetImageStride()

Returns the image stride (bytes per row).

public int GetImageStride()

Returns

int

GetPalette()

Retrieves the color table for indexed pixel formats, or null for other formats.

public GcWicBitmap.Palette GetPalette()

Returns

GcWicBitmap.Palette

Import(GcBitmap)

Loads the image from an instance of the GcBitmap class.

If the source image is not opaque, the color channels must be premultiplied with the alpha channel.

public void Import(GcBitmap sourceBitmap)

Parameters

sourceBitmap GcBitmap

The source GcBitmap.

See Also

Import(GcWicBitmap)

Loads the image from another instance of GcWicBitmap.

public void Import(GcWicBitmap sourceWicBitmap)

Parameters

sourceWicBitmap GcWicBitmap

The source GcWicBitmap.

Import(byte[], int, int, WicPixelFormat)

Loads the image from a byte array containing the pixels buffer.

public void Import(byte[] bytes, int width, int height, WicPixelFormat pixelFormat)

Parameters

bytes byte[]

The source byte array with pixel buffer.

width int

The width of the image, in pixels.

height int

The height of the image, in pixels.

pixelFormat WicPixelFormat

The pixel format of the image.

Import(byte[], int, int, int, WicPixelFormat)

Loads the image from a byte array containing the pixels buffer with specified stride (bytes per row of pixels).

public void Import(byte[] bytes, int stride, int width, int height, WicPixelFormat pixelFormat)

Parameters

bytes byte[]

The source byte array with pixel buffer.

stride int

The stride (bytes per row) of the image data in the source byte array.

width int

The width of the image, in pixels.

height int

The height of the image, in pixels.

pixelFormat WicPixelFormat

The pixel format of the image.

Import(IntPtr, int, int, WicPixelFormat)

Loads the image from the unmanaged block of memory pointed by IntPtr.

public void Import(IntPtr srcPtr, int width, int height, WicPixelFormat pixelFormat)

Parameters

srcPtr System.IntPtr

The pointer to the beginning of the unmanaged block of memory.

width int

The width of the image, in pixels.

height int

The height of the image, in pixels.

pixelFormat WicPixelFormat

The pixel format of the image.

Import(IntPtr, int, int, int, WicPixelFormat)

Loads the image from a unmanaged block of memory pointed by IntPtr and having the specified stride (bytes per row of pixels).

public void Import(IntPtr srcPtr, int stride, int width, int height, WicPixelFormat pixelFormat)

Parameters

srcPtr System.IntPtr

The pointer to the beginning of the unmanaged block of memory.

stride int

The stride (bytes per row) of the source image data.

width int

The width of the image, in pixels.

height int

The height of the image, in pixels.

pixelFormat WicPixelFormat

The pixel format of the image.

ImportAsFragment(GcBitmap, int, int)

Loads a GcBitmap at the given destination within the image.

If the source image is not opaque, the color channels must be premultiplied with the alpha channel.

public void ImportAsFragment(GcBitmap sourceBitmap, int xDst, int yDst)

Parameters

sourceBitmap GcBitmap

The source GcBitmap.

xDst int

The destination X pixel coordinate within the target bitmap.

yDst int

The destination Y pixel coordinate within the target bitmap.

See Also

ImportAsFragment(GcWicBitmap, int, int)

Loads another GcWicBitmap at the given destination within the image.

public void ImportAsFragment(GcWicBitmap sourceWicBitmap, int xDst, int yDst)

Parameters

sourceWicBitmap GcWicBitmap

The source GcWicBitmap.

xDst int

The destination X pixel coordinate within the target bitmap.

yDst int

The destination Y pixel coordinate within the target bitmap.

ImportAsFragment(byte[], Rectangle)

Loads the pixel buffer from a byte array at the given destination within the image.

public void ImportAsFragment(byte[] bytes, Rectangle dstRect)

Parameters

bytes byte[]

The source byte array with pixel buffer.

dstRect System.Drawing.Rectangle

The destination rectangle within the target bitmap.

ImportAsFragment(IntPtr, Rectangle)

Copies the unmanaged block of memory ato the given destination within the image.

public void ImportAsFragment(IntPtr srcPtr, Rectangle dstRect)

Parameters

srcPtr System.IntPtr

The pointer to the beginning of the unmanaged block of memory.

dstRect System.Drawing.Rectangle

The destination rectangle within the target bitmap.

Load(Stream, params BaseTransform[])

Loads the image from a System.IO.Stream. JPEG, PNG, GIF, BMP, TIFF, ICO, JPEG XR formats are supported.

public void Load(Stream stream, params BaseTransform[] transforms)

Parameters

stream System.IO.Stream

The input stream.

transforms BaseTransform[]

The transformation chain for the image that is being loaded.

Load(Stream, WicContainerFormat, int, Rectangle?, params BaseTransform[])

Loads the image from a System.IO.Stream. JPEG, PNG, GIF, BMP, TIFF, ICO, JPEG XR formats are supported.

public void Load(Stream stream, WicContainerFormat containerFormat, int frameIndex, Rectangle? imageRect, params BaseTransform[] transforms)

Parameters

stream System.IO.Stream

The input stream.

containerFormat WicContainerFormat

The image container format; use Unknown to detect the format automatically.

frameIndex int

Index of an image frame to read, pass 0 for image formats not supporting multiple frames.

imageRect System.Drawing.Rectangle?

Clipping rectangle for the image after all transformations.

transforms BaseTransform[]

The transformation chain for the image that is being loaded.

Load(string, params BaseTransform[])

Loads the image from a file. JPEG, PNG, GIF, BMP, TIFF, ICO, JPEG XR formats are supported.

public void Load(string path, params BaseTransform[] transforms)

Parameters

path string

The file path to the image.

transforms BaseTransform[]

The transformation chain for the image that is being loaded.

Load(string, WicContainerFormat, int, Rectangle?, params BaseTransform[])

Loads the image from a file. JPEG, PNG, GIF, BMP, TIFF, ICO, JPEG XR formats are supported.

public void Load(string path, WicContainerFormat containerFormat, int frameIndex, Rectangle? imageRect, params BaseTransform[] transforms)

Parameters

path string

The file path to the image.

containerFormat WicContainerFormat

The image container format; use Unknown to detect the format automatically.

frameIndex int

Index of an image frame to read, pass 0 for image formats not supporting multiple frames.

imageRect System.Drawing.Rectangle?

Clipping rectangle for the image after all transformations.

transforms BaseTransform[]

The transformation chain for the image that is being loaded.

PixelFormatFromGuid(Guid)

Converts a GUID of the WIC pixel format to the PixelFormat enumeration value.

public static WicPixelFormat PixelFormatFromGuid(Guid pfGuid)

Parameters

pfGuid System.Guid

The GUID of the WIC pixel format.

Returns

WicPixelFormat

PixelFormatToGuid(WicPixelFormat)

Returns a GUID of the corresponding WIC pixel format for the given value of the PixelFormat enumeration.

public static Guid PixelFormatToGuid(WicPixelFormat pixelFormat)

Parameters

pixelFormat WicPixelFormat

The PixelFormat enumeration value.

Returns

System.Guid

Save(Stream, WicContainerFormat, BaseOptions)

Saves the image to a System.IO.Stream using the specified format and options.

public void Save(Stream stream, WicContainerFormat format, BaseOptions options = null)

Parameters

stream System.IO.Stream

The output stream.

format WicContainerFormat

The container format that determines the image encoder.

options BaseOptions

The options for the specified image encoder.

Save(string, WicContainerFormat, BaseOptions)

Saves the image to a file using the specified format and options.

public void Save(string fileName, WicContainerFormat format, BaseOptions options = null)

Parameters

fileName string

The output file name.

format WicContainerFormat

The container format that determines the image encoder.

options BaseOptions

The options for the specified image encoder.

SaveAsBmp(Stream, BmpOptions)

Saves the image to a System.IO.Stream in BMP format.

public void SaveAsBmp(Stream stream, BmpOptions options = null)

Parameters

stream System.IO.Stream

The output stream.

options BmpOptions

The options for the BMP image encoder.

SaveAsBmp(string, BmpOptions)

Saves the image to a file in BMP format.

public void SaveAsBmp(string fileName, BmpOptions options = null)

Parameters

fileName string

The output file name.

options BmpOptions

The options for the BMP image encoder.

SaveAsGif(Stream, GifOptions)

Saves the image to a System.IO.Stream in GIF format.

public void SaveAsGif(Stream stream, GifOptions options = null)

Parameters

stream System.IO.Stream

The output stream.

options GifOptions

The options for the GIF image encoder.

SaveAsGif(string, GifOptions)

Saves the image to a file in GIF format.

public void SaveAsGif(string fileName, GifOptions options = null)

Parameters

fileName string

The output file name.

options GifOptions

The options for the GIF image encoder.

SaveAsJpeg(Stream, JpegOptions)

Saves the image to a System.IO.Stream in JPEG format.

public void SaveAsJpeg(Stream stream, JpegOptions options = null)

Parameters

stream System.IO.Stream

The output stream.

options JpegOptions

The options for the JPEG image encoder.

SaveAsJpeg(string, JpegOptions)

Saves the image to a file in JPEG format.

public void SaveAsJpeg(string fileName, JpegOptions options = null)

Parameters

fileName string

The output file name.

options JpegOptions

The options for the JPEG image encoder.

SaveAsJpegXR(Stream, JpegXROptions)

Saves the image to a System.IO.Stream in JPEG XR format.

public void SaveAsJpegXR(Stream stream, JpegXROptions options = null)

Parameters

stream System.IO.Stream

The output stream.

options JpegXROptions

The options for the JPEG XR image encoder.

SaveAsJpegXR(string, JpegXROptions)

Saves the image to a file in JPEG XR format.

public void SaveAsJpegXR(string fileName, JpegXROptions options = null)

Parameters

fileName string

The output file name.

options JpegXROptions

The options for the JPEG XR image encoder.

SaveAsPng(Stream, PngOptions)

Saves the image to a System.IO.Stream in PNG format.

public void SaveAsPng(Stream stream, PngOptions options = null)

Parameters

stream System.IO.Stream

The output stream.

options PngOptions

The options for the PNG image encoder.

SaveAsPng(string, PngOptions)

Saves the image to a file in PNG format.

public void SaveAsPng(string fileName, PngOptions options = null)

Parameters

fileName string

The output file name.

options PngOptions

The options for the PNG image encoder.

SaveAsTiff(Stream, TiffOptions)

Saves the image to a System.IO.Stream in TIFF format.

public void SaveAsTiff(Stream stream, TiffOptions options = null)

Parameters

stream System.IO.Stream

The output stream.

options TiffOptions

The options for the TIFF image encoder.

SaveAsTiff(string, TiffOptions)

Saves the image to a file in TIFF format.

public void SaveAsTiff(string fileName, TiffOptions options = null)

Parameters

fileName string

The output file name.

options TiffOptions

The options for the TIFF image encoder.

SetDpi(float, float)

Changes the physical resolution of the image.

public void SetDpi(float dpiX, float dpiY)

Parameters

dpiX float

The horizontal resolution.

dpiY float

The vertical resolution.

SetDpi(float)

Changes the physical resolution of the image.

public void SetDpi(float dpi)

Parameters

dpi float

The horizontal and vertical resolution.

SetFontCache(FontCache)

Assigns a shared instance of the GrapeCity.Documents.Imaging.Windows.GcWicBitmap.FontCache object.

public void SetFontCache(FontCache fontCache)

Parameters

fontCache FontCache

SetLicenseKey(string)

Sets the license key.

public static void SetLicenseKey(string key)

Parameters

key string

The license key to set.

SetPalette(Palette)

Sets the new color table for the bitmap.

public void SetPalette(GcWicBitmap.Palette palette)

Parameters

palette GcWicBitmap.Palette

ToByteArray()

Stores the image buffer to a byte array (without the palette and metadata information).

public byte[] ToByteArray()

Returns

byte[]

ToByteArray(Rectangle)

Stores a rectangular area of the image to a byte array.

public byte[] ToByteArray(Rectangle srcRect)

Parameters

srcRect System.Drawing.Rectangle

The source rectangle within the image.

Returns

byte[]

ToByteArray(out int)

Stores the image buffer to a byte array with the same stride (bytes per row).

public byte[] ToByteArray(out int stride)

Parameters

stride int

Returns the stride (bytes per row) of the image.

Returns

byte[]

ToGcBitmap(GcBitmap, bool)

Stores the image buffer into an existing instance of GcBitmap.

public void ToGcBitmap(GcBitmap bmp, bool updatePixelFormat = false)

Parameters

bmp GcBitmap

The destination GcBitmap object.

updatePixelFormat bool

Indicates if all pixels should be converted from premultiplied alpha format or to opaque format with alpha = 255.

ToGcBitmap(bool)

Stores the image buffer to a GcBitmap.

public GcBitmap ToGcBitmap(bool updatePixelFormat = false)

Parameters

updatePixelFormat bool

Indicates if all pixels should be converted from premultiplied alpha format or to opaque format with alpha = 255.

Returns

GcBitmap

ToGcBitmap(Rectangle, bool)

Stores a rectangular area of the image to a GcBitmap.

public GcBitmap ToGcBitmap(Rectangle srcRect, bool updatePixelFormat = false)

Parameters

srcRect System.Drawing.Rectangle

The source rectangle within the image.

updatePixelFormat bool

Indicates if all pixels should be converted from premultiplied alpha format or to opaque format with alpha = 255.

Returns

GcBitmap

Transform(params BaseTransform[])

Creates a new instance of GcWicBitmap as a copy of the current bitmap passed through the set of transformations.

public GcWicBitmap Transform(params BaseTransform[] transforms)

Parameters

transforms BaseTransform[]

The transformation chain, can be empty to just copy the image.

Returns

GcWicBitmap