Online Help for Chasys Draw IES: SDK - Callback Suites - pi_BasicImage

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. Both objects are defined in plugin.h.

#define PI_BASICIMAGE_VERSION                         0x00010016 // 22 Sep 2023


struct pibi_IMAGE


      unsigned long width;

      unsigned long height;

      unsigned long pitch;

      unsigned long unused;

      unsigned long *p_pix;

      void          *reserved;



struct pibi_RECT


      long x0;

      long y0;

      long x1;

      long y1;

      bool valid;



struct pibi_FILEINFO


      HWND           hwnd;

      const wchar_t* file;

      void*          memfile_data;

      unsigned long  memfile_size;

      wchar_t*       memfile_type_hint;

      bool           get_metadata;

      void*          metadata_ptr;

      unsigned long  metadata_size;

      bool           is_known;

      bool           bad_host;



struct pi_BASICIMAGE


      unsigned long   version;

      unsigned long   host_id;


      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);

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


      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;//do not touch


      int (__cdecl*   load_file)(pibi_IMAGE* img,pibi_FILEINFO* info);

      int (__cdecl*   save_file)(pibi_IMAGE* img,pibi_FILEINFO* info);

      void*           reserved_2;//do not touch

      void*           reserved_3;//do not touch


      int (__cdecl*   copy)(pibi_IMAGE* img,pibi_IMAGE* src);

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

      int (__cdecl*   flip)(pibi_IMAGE* img,unsigned long options);

      int (__cdecl*   rotate)(pibi_IMAGE* img,int direction);


      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*   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 rop_param);

      int (__cdecl*   quad_blit)(

                          pibi_IMAGE* dst,int x0,int y0,int x1,int y1,int x2,int y2,int x3,int y3,

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

                          unsigned long options,unsigned long rop_param);

      int (__cdecl*   blit_DC)(

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

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

                          unsigned long options);


      int (__cdecl*   translate)(

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

                          const unsigned char *lut_r,const unsigned char *lut_g,

                          const unsigned char *lut_b,const unsigned char *lut_a,

                          unsigned long options,const void* param);

      int (__cdecl*   convolute)(

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

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

                          unsigned long mask,unsigned long options);

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

      void*           reserved_4;//do not touch


      int (__cdecl*   polar)(

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

                          pibi_IMAGE* src,int center_x,int center_y,

                          unsigned long options);

      void*           reserved_5;//do not touch

      void*           reserved_6;//do not touch

      void*           reserved_7;//do not touch


      unsigned char   reserved_x[1024-128];//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_MAXQUALITY                         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 ::flip()

#define PI_BI_FLIP_HORZ                               0x00000001

#define PI_BI_FLIP_VERT                               0x00000002


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

//also used for "rop_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_DIV                 0x00090000

      #define PI_BI_FILL_RASTEROP_OFF                 0x000a0000

      #define PI_BI_FILL_RASTEROP_MIN                 0x000b0000

      #define PI_BI_FILL_RASTEROP_MAX                 0x000c0000

      #define PI_BI_FILL_RASTEROP_DIFF                0x000d0000

      #define PI_BI_FILL_RASTEROP_OUT                 0x000e0000

      #define PI_BI_FILL_RASTEROP_TEX1                0x000f0000

      #define PI_BI_FILL_RASTEROP_TEX2                0x00100000

      #define PI_BI_FILL_RASTEROP_SCRN                0x00110000

      #define PI_BI_FILL_RASTEROP_OVER                0x00120000

      #define PI_BI_FILL_RASTEROP_DODG                0x00130000

      #define PI_BI_FILL_RASTEROP_BURN                0x00140000

      #define PI_BI_FILL_RASTEROP_LUM                 0x00150000

      #define PI_BI_FILL_RASTEROP_CLR                 0x00160000

      #define PI_BI_FILL_RASTEROP_HUE                 0x00170000

      #define PI_BI_FILL_RASTEROP_SAT                 0x00180000

      #define PI_BI_FILL_RASTEROP_VAL                 0x00190000

      #define PI_BI_FILL_RASTEROP_LIT                 0x001a0000

      #define PI_BI_FILL_RASTEROP_MASK                0x007d0000


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

#define PI_BI_POLAR_XY_TO_RQ                          0x00000000

#define PI_BI_POLAR_RQ_TO_XY                          0x00000001

#define PI_BI_POLAR_INVERT_RQ                         0x00000002

#define PI_BI_POLAR_ACCURATE                          0x00004000


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 after use.

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 and nulls out the variable; you must call this function before you start accessing the image data 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.

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. Returns -1 if the images are exactly the same and marks the returned rectangle as invalid. A return of 0 indicates an error.

polar() allows you to convert an image from cartesian to polar coordinates and vice-versa. Returns 1 to indicate success.

load_file() 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. You have the option of using a memory buffer as the source instead of a file. In this case, the memfile_type_hint member of pibi_FILEINFO, 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.

If you ask for metadata, you must free metadata_ptr using GlobalFree().

save_file() 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.

The following macros may be useful when using this interface:



//Macro for converting pixels between ARGB and ABGR

#define plg_swap_rgb(c)             ((c&0xff00ff00)|((c>>16)&0x000000ff)|((c<<16)&0x00ff0000))



//Macro for restricting a value to a given set of limits

#define plg_limit_value(a,lo,hi)    { if((a)<(lo)){a=(lo);} else if((a)>(hi)){a=(hi);} }



//Macro for checking a value against a given set of limits

#define plg_not_in_range(a,lo,hi)   ((a<(lo))||(a>(hi)))


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-2024

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