back to Table of Contents

Common Inputs

All effect functions in this library use a regular set of common inputs. However, some of the effects may also require its specific inputs, which are then noted in the respective effect description.

Image handles

shan& (LONG)

• The handle of the 32-bit ARGB source image you wish to process.
  • Valid image handle values are usually less than -1.
  • A value of zero (0) is also valid and designates the current screen.

mask& (LONG)

• The handle of any 8-bit image to use as mask, or -1.
  • If given, then the mask must be an 8-bit (256 colors) image of the very same size as the given source image. Each source pixel is then only subject to process, if its respective pixel in the mask is drawn in any color <> 0, hence colors 1-255.

Limit the processing area

minX% (INTEGER)

• The leftmost pixel column of the image area to process.

minY% (INTEGER)

• The topmost pixel row of the image area to process.

maxX% (INTEGER)

• The rightmost pixel column of the image area to process.

maxY% (INTEGER)

• The bottom-most pixel row of the image area to process.

Note these limits are clipped according to the source image boundaries. If you don't need a particular limit, then simply set it to -1. If all limits are -1, then the entire image will be processed, unless a mask image is given.

Common Result

All effect functions in this library do also return the same result on success or an invalid handle on failure, so make sure to check for this.

Image handles

newImg& (LONG)

• The handle of the new (processed) 32-bit ARGB image.
  • As usual, valid handles have values less than -1.

Failure may be caused by four common reasons:

1. You did provide an invalid source image handle (>= -1 and <> 0).
2. The source image was not in 32-bit ARGB mode.
3. The function could not obtain a new image handle (Out of Memory?).
4. A given mask image was not in 8-bit (256 colors) mode or did not match the source image size.

The original passed in source images remain unchanged, so you can simply collect all handles of a multiple effect sequence using an array or stack for easy undo/redo operations. That said, means you are responsible to _FREEIMAGE no longer needed images.

Also any passed in mask images remain unchanged and the active _SOURCE and _DEST handles are not changed either by any effects.

back to Table of Contents