WICBitmap Reference

Reference for the WICBitmap object, which loads, converts, draws, and saves images. It uses the Windows Imaging Component (WIC).

• Related: te Reference, api Reference, FolderItems Reference, Memory Reference
• Source: the implementation of methodGB[] and CteWICBitmap (Invoke, GetHBITMAP, GetEncoderClsid, CreateStream, RotateFlip, and others) in TE/objects.cpp

Notation: P = property, M = method. Member names are matched case-insensitively.

Table of Contents

1. How to Obtain
2. Loading and Creating
3. Saving and Encoding
4. Size and Pixel Operations
5. Conversion and Processing
6. Frames and Metadata
7. Conversion for GDI and Drawing
8. Codec Information
9. Events
10. Examples

1. How to Obtain

const image = api.CreateObject("WICBitmap");   // recommended
const image2 = te.WICBitmap;                   // te.WICBitmap is also the same (a new object is created on every reference)

te.GdiplusBitmap is an old name and is deprecated (the same object is returned).

Rules (important)

• When you call a load/create method (From*, Create, Free), the image held until then is always discarded. It stays discarded even if the call fails.
• Load/create methods return themselves (this) on success and empty (undefined) on failure. Check for success before using the result, as follows. javascript const image = api.CreateObject("WICBitmap").FromFile(path); if (image) { /* usable */ }
• If you call a method that needs an image (saving, getting the size, processing, converting, drawing), such as GetWidth, while no image is held, it does nothing and returns empty (it is not an error).
• In an environment where WIC cannot be initialized, all methods do nothing.
• Pixel values are handled as integers in the 0xAARRGGBB form (the internal format is 32bpp BGRA).

2. Loading and Creating

• At load time, JPEG and similar images are automatically rotated/flipped according to the EXIF orientation information (/app1/ifd/{ushort=274}).
• If a file could not be read with FromFile, OnGetAlt (Chapter 9) is set, and the path is under TE's temporary folder (%TEMP%\tablacus\), getting an alternative path is also attempted.
• The original data (the stream) is kept when bKeepStream of FromSource is true, when the image has multiple frames, or when it was loaded on a thread other than the main thread (FromFile / FromStream do not keep it in normal main-thread loading. In that case, even if you specify -2 for the quality of Save / DataURI, the original data cannot be output).

3. Saving and Encoding

The output format is determined from the string in the first argument. Both a MIME type ("image/png") and a file name / extension ("a.jpg", ".jpg") can be used. You can look up the available encoders with GetCodecInfo (Chapter 8).

When type is omitted: if the original data is kept (such as with bKeepStream of FromSource), it is the original format; otherwise it is image/png.

quality

4. Size and Pixel Operations

• GetPixel / SetPixel / FillRect / Mask / AlphaBlend convert the image to 32bpp BGRA before processing, so the format of images in other formats changes.
• The pixel color order is 0xAARRGGBB. It differs from the order of a GetRValue-style COLORREF (0x00BBGGRR).

5. Conversion and Processing

For DrawEx, DrawText, GetHBITMAP, and GetHICON, see Chapter 7.

6. Frames and Metadata

7. Conversion for GDI and Drawing

8. Codec Information

GetCodecInfo(type, mode, array)

Looks up information about the codecs registered with WIC and appends the result to array (an object that has a push method, such as api.Array() or []). 3 arguments are required.

const ar = [];
image.GetCodecInfo(2, 1, ar);   // list of the MIME types of the encoders
// The contents of the result differ by environment (values such as `image/png` are included, separated by commas)

It can be called even when no image is held.

9. Events

10. Examples

// Load a file, create a thumbnail, and save it as PNG
const image = api.CreateObject("WICBitmap").FromFile("C:\\Pictures\\a.jpg");
if (image) {
    const thumb = image.GetThumbnailImage(128, 128);
    thumb.Save("C:\\Temp\\thumb.png");
}

// DataURI (to embed in HTML)
const uri = image.DataURI("image/jpeg", 80);

// Take it out in the original format (without re-encoding)
const src = api.CreateObject("WICBitmap").FromSource(api.SHCreateStreamOnFileEx("C:\\Pictures\\a.gif", 0, 0, false), true);
const raw = src.DataURI("", -2);

// Create a new image and manipulate pixels
const bmp = api.CreateObject("WICBitmap").Create(100, 100);
bmp.FillRect(0, 0, 100, 100, 0xFFFF0000);   // opaque red
bmp.SetPixel(50, 50, 0xFF0000FF);           // blue
const c = bmp.GetPixel(50, 50);

// Rotate and replace (90° to the right)
image.RotateFlip(1);

// A bitmap for icons / menus
const hbm = image.GetHBITMAP(-2);
// ... after use ...
api.DeleteObject(hbm);

// Look up the available encoders
const types = [];
image.GetCodecInfo(2, 1, types);

When you pass an IStream directly, as in FromSource(api.SHCreateStreamOnFileEx(…)), adjust the call to match the arguments of api.SHCreateStreamOnFileEx (api Reference).

Related

• te Reference
• api Reference
• FolderItems Reference
• Memory Reference