Renders a bitmap image in the effect pipeline.
The ImageFX class will render a source image into a given rectangle within the current user coordinate system. The client has the option of providing a pre-allocated Bitmap or the path to a Image file as the source.
If a pre-allocated Bitmap is to be used, it must be created under the ownership of the ImageFX object, and this must be configured prior to initialisation. It is required that the bitmap uses 32 bits per pixel and that the alpha channel is enabled.
If a source image file is referenced, it will be upscaled to meet the requirements automatically as needed.
Technically the ImageFX object is represented by a new viewport, the bounds of which are defined by attributes X, Y, Width and Height. The placement and scaling of the referenced image is controlled by the AspectRatio field.
The ImageFX class consists of the following fields:
Access | Name | Type | Comment | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| AspectRatio | ARF | SVG compliant aspect ratio settings. | |||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
| Bitmap | OBJECTPTR | The Bitmap being used as the image source. | |||||||||||||||||||||||||||||
Reading the Bitmap field will return the Bitmap that is being used as the image source. Note that if a custom Bitmap is to be used, the correct way to do this as to assign it to the ImageFX object via ownership rules. If an image has been processed by setting the Path, the Bitmap will refer to the content that has been processed. | |||||||||||||||||||||||||||||||
| Path | STRING | Path to an image file supported by the Image class. | |||||||||||||||||||||||||||||
| ResampleMethod | VSM | The resample algorithm to use for transforming the source image. | |||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
| XMLDef | STRING | Returns an SVG compliant XML string that describes the filter. | |||||||||||||||||||||||||||||
The following actions are currently supported:
| Draw | Render the effect to the target bitmap. | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
ERR acDraw(*Object, DOUBLE X, DOUBLE Y, DOUBLE Width, DOUBLE Height)
| ||||||||||||
Aspect ratios control alignment, scaling and clipping.
| Name | Description |
|---|---|
| ARF::MEET | Aspect ratio is preserved. The entire viewbox will be visible in the viewport. The viewbox is scaled up as much as possible. |
| ARF::NONE | Scale the viewbox to match the size of the viewport. Aspect ratio is not preserved. |
| ARF::SLICE | Aspect ratio is preserved. The viewbox can extend beyond the viewport's edges on one axis. The viewbox is scaled up as much as possible. |
| ARF::X_MAX | Align to the right. |
| ARF::X_MID | Align to the horizontal center. |
| ARF::X_MIN | Align to the left. |
| ARF::Y_MAX | Align to the bottom. |
| ARF::Y_MID | Align to the vertical center. |
| ARF::Y_MIN | Align to the top. |
| Name | Description |
|---|---|
| VSM::AUTO | The default option is chosen by the system. This will typically be BILINEAR, but slow machines may switch to nearest neighbour and high speed machines could use more advanced methods. |
| VSM::BESSEL | Uses a broad Bessel filter that can preserve detail during resampling, but is slower than the smaller-kernel methods. |
| VSM::BICUBIC | Produces a similar result to BILINEAR at a slightly higher CPU cost and a marginally sharper after-effect. |
| VSM::BILINEAR | Bilinear is a common algorithm that produces a reasonable quality image quickly. |
| VSM::BLACKMAN | Five times slower than BILINEAR, the final result will be less sharp than SINC. |
| VSM::GAUSSIAN | Uses a Gaussian filter that softens the result, reducing aliasing at the cost of sharp edge detail. |
| VSM::KAISER | Uses a Kaiser-windowed filter, giving smooth interpolation with low ringing and a cost close to BILINEAR. |
| VSM::LANCZOS | This well known algorithm may serve as a point of comparison for evaluating the results of other methods. It shares characteristics with SINC and BLACKMAN. |
| VSM::MITCHELL | Uses a Mitchell-Netravali filter, balancing sharpness and smoothness at a cost similar to BICUBIC. |
| VSM::NEIGHBOUR | Nearest neighbour is the fastest sampler at the cost of poor quality. |
| VSM::QUADRIC | Uses a quadratic filter with a modest kernel, giving smoother results than BILINEAR with limited extra cost. |
| VSM::SINC | Five times slower than BILINEAR, the final result is of very good quality. |
| VSM::SPLINE16 | About twice as slow as BILINEAR, this method samples a 4x4 area and produces a considerably better result, and is a good choice for enlarging images without producing artifacts when contrasting colours are present. |