Chasys Draw IES Help:

SDK - Callback Suites - pi_BasicImage

SDK - Callback Suites - pi_BasicImage

Callback Overview

This callback suite provides the plug-in with basic image allocation and management functionality. These include allocation, deallocation, GDI interoperability, and blitting/blending.


Callback Interface Description

This interface represents an image as an instance of an object of type pibi_IMAGE. The interface itself is encapsulated in an object of type pi_BASICIMAGE.



#define PI_BASICIMAGE_VERSION                         0x00010008


struct pibi_IMAGE


      unsigned long width;

      unsigned long height;

      unsigned long pitch;

      unsigned long unused;

      unsigned long *p_pix;

      void          *reserved;



struct pi_BASICIMAGE


      unsigned long version;

      unsigned long unused_1;


      int (__cdecl* create)(pibi_IMAGE* img,int width,int height);

      int (__cdecl* virtualize)(pibi_IMAGE* img,int width,int height,

            int pitch,unsigned long* p_pix);

      int (__cdecl* destroy)(pibi_IMAGE* img);

      void* reserved_0;


      int (__cdecl* lock)(pibi_IMAGE* img);

      int (__cdecl* unlock)(pibi_IMAGE* img);


      HDC (__cdecl* gdi_getDC)(pibi_IMAGE* img);

      int (__cdecl* gdi_freeDC)(pibi_IMAGE* img,HDC hdc);

      HBITMAP (__cdecl* gdi_makeHBMP)(pibi_IMAGE* img);

      void* reserved_1;


      int (__cdecl* blit)(

            pibi_IMAGE* dst,int dx0,int dy0,int dx1,int dy1,

            pibi_IMAGE* src,int sx0,int sy0,int sx1,int sy1,

            unsigned long options,unsigned long param);

      int (__cdecl* fill)(

            pibi_IMAGE* img,int x0,int y0,int x1,int y1,

            unsigned long color1,unsigned long color2,

            unsigned long color3,unsigned long color4,

            unsigned long options,int param1,int param2);

      int (__cdecl* blitToDC)(

            HDC hdc,int dx0,int dy0,int dx1,int dy1,

            pibi_IMAGE* src,int sx0,int sy0,int sx1,int sy1,

            unsigned long options,unsigned long param);

      void* reserved_2;


      int (__cdecl* translate)(

            pibi_IMAGE* img,int x0,int y0,int x1,int y1,

            unsigned char *lut_r,unsigned char *lut_g,

            unsigned char *lut_b,unsigned char *lut_a,

            unsigned long options,void* param);

      int (__cdecl* transform)(

            pibi_IMAGE* img,int x0,int y0,int x1,int y1,

            double *matrix_5x4,unsigned long options);

      int (__cdecl* convolute)(

            pibi_IMAGE* dst,int x0,int y0,int x1,int y1,

            pibi_IMAGE* src,double *matrix,int mat_cols,int mat_rows,

            unsigned long mask,unsigned long options);

      int (__cdecl* compare)(pibi_IMAGE* img1,pibi_IMAGE* img2,RECT *rt_diff);


      int (__cdecl* loadFile)(pibi_IMAGE* img,wchar_t* file,HWND hwnd);

      int (__cdecl* saveFile)(pibi_IMAGE* img,wchar_t* file,HWND hwnd);

      int (__cdecl* loadMemFile)(pibi_IMAGE* img,void* data,int size,

           wchar_t* type_hint,HWND hwnd);

      void* reserved_3;


      unsigned char     reserved_x[1024-96];//do not touch



//flags for the "options" parameter of ::blit()

#define PI_BI_BLIT_BLOCKY                             0x00000000

#define PI_BI_BLIT_STRETCH                            0x00000001

#define PI_BI_BLIT_HQ_STRETCH                         0x00000002

#define PI_BI_BLIT_ALPHABLEND                         0x00000010

#define PI_BI_BLIT_RASTEROP                           0x00000020

#define PI_BI_BLIT_TILE_xxx                           0x00030000

      #define PI_BI_BLIT_TILE_NORMAL                  0x00010000

      #define PI_BI_BLIT_TILE_INVERT                  0x00020000


//flags for the "options" parameter of ::fill()

//also used for "param" for blit::PI_BI_BLIT_RASTEROP

#define PI_BI_FILL_SHAPE_xxx                          0x0000000f

      #define PI_BI_FILL_RECTANGLE                    0x00000000

      #define PI_BI_FILL_ELLIPSE                      0x00000001

      #define PI_BI_FILL_ROUNDRECT                    0x00000002

#define PI_BI_FILL_ALPHABLEND                         0x00000010

#define PI_BI_FILL_GRADIENT                           0x00000020

#define PI_BI_FILL_RASTEROP_xxx                       0x00ff0000

      #define PI_BI_FILL_RASTEROP_NONE                0x00000000

      #define PI_BI_FILL_RASTEROP_OR                  0x00010000

      #define PI_BI_FILL_RASTEROP_AND                 0x00020000

      #define PI_BI_FILL_RASTEROP_XOR                 0x00030000

      #define PI_BI_FILL_RASTEROP_ADD                 0x00040000

      #define PI_BI_FILL_RASTEROP_SUB                 0x00050000

      #define PI_BI_FILL_RASTEROP_INC                 0x00060000

      #define PI_BI_FILL_RASTEROP_DEC                 0x00070000

      #define PI_BI_FILL_RASTEROP_MUL                 0x00080000

      #define PI_BI_FILL_RASTEROP_OUT                 0x00090000

      #define PI_BI_FILL_RASTEROP_OFF                 0x000a0000

      #define PI_BI_FILL_RASTEROP_HUE                 0x000b0000

      #define PI_BI_FILL_RASTEROP_CLR                 0x000c0000

      #define PI_BI_FILL_RASTEROP_LUM                 0x000d0000

      #define PI_BI_FILL_RASTEROP_SCRN                0x000e0000

      #define PI_BI_FILL_RASTEROP_MASK                0x000f0000

      #define PI_BI_FILL_RASTEROP_TEX                 0x00100000

      #define PI_BI_FILL_RASTEROP_DIV                 0x00110000

      #define PI_BI_FILL_RASTEROP_DIFF                0x00120000

      #define PI_BI_FILL_RASTEROP_MIN                 0x00130000

      #define PI_BI_FILL_RASTEROP_MAX                 0x00140000

      #define PI_BI_FILL_RASTEROP_SAT                 0x00150000

      #define PI_BI_FILL_RASTEROP_OVER                0x00160000


create() creates a new image.

virtualize() creates a virtual image, basically one that encapsulates the provided parameters. This is useful for turning the image data returned from Chasys Draw IES into a pibi_IMAGE. For a code example, see the source-code for the NS Contrast plug-in.

destroy() destroys an image. Both real and virtual images have to be destroyed when nolonger needed.

lock() prepares an image for direct access. unlock() undoes this.

gdi_getDC() returns a GDI-compatible HDC that can be used with all GDI functions. gdi_freeDC() frees this HDC; you must call this function before you start accessing the surface directly again.

blit() allows you to do bitmap copies. You can also stretch/shrink the image and perform alpha-blending using this function, by setting the appropriate flags.

fill() allows you to do bitmap fills. You can also do basic shapes, gradients and perform alpha-blending and raster operations using this function, by setting the appropriate flags.

translate() takes look-up tables as its inputs and exchanges each existing pixel value with the corresponding value in the table. This is ideal for level-shifting, as would be needed for adjusting brightness. For a code example, see the source-code for the NS Contrast plug-in.

transform() allows you to do color-channel manipulations using matrices (color transformations). The input matrix defines that mixture of the existing channel information that would comprise each output pixel, and is always 5x4.

convolute() allows you to do spatial convolution using matrices (refered to in some texts as “filtering”). Useful for things like gaussian blur. Input matrix dimensions are restricted to the range 2x2 to 32x32.

compare() allows you to generate a difference rectangle - a rectangle containing the portion of one image that is different from the corresponding area in the other image. Useful for detecting similar frames (or areas in frames) in animations.

loadFile() allows you to load an image file into a pibi_IMAGE. Any file that can be loaded by Chasys Draw IES can be loaded by this function. The function returns a simple image; layered images are flattened and only the first frame of an animation is loaded.

saveFile() allows you to save an image file contained in a pibi_IMAGE to a file. The format is determined by the file extension. Any file that can be saved by Chasys Draw IES can be saved by this function. The function returns a non-zero value if the image was saved successfully.

loadMemFile() performs the same function as loadFile() but using a memory buffer as the source instead of a file. The type_hint parameter, if not null, specifies a string from which Chasys Draw IES can retrieve the file extension; this can either be the extension itself preceeded by a period (e.g. “.jpg”) or the full file name. Specifying the type hint allows Chasys Draw IES to guess which plug-in to use, thus avoiding the overhead associated with testing the data against all installed plug-ins.

The following macros may be useful when using this interface:



The internal implementations of pi_BasicImage and pibi_IMAGE are neither defined nor fixed, and are purely host dependent. Do not attempt to access the reserved portion of the objects.



Copyright © John Paul Chacha, 2001-2017

The information herein is subject to change without any notice. The author makes no guarantees as to the completeness of this documentation.