Class TCastleImage

Check that both images have the same sizes and Second image class descends from First image class. If not, raise appropriate ELerpXxx exceptions.

Some implementation of TRGBImage.LerpWith may require other checks (since LerpWith may be sometimes allowed between unequal classes), so this doesn't have to be used by all TRGBImage.LerpWith implementations (although it's comfortable for simple implementations).

Like DrawFrom, but can assume that all coordinates and sizes are valid. Override this to add copying using some more sophisticated method than just memory copying (so also for handling mode other than dmBlend).

Constructor without parameters creates image with Width = Height = Depth = 0 and RawPixels = nil, so IsEmpty will return True.

This is equivalent to SetSize(0, 0, 0). It sets Width = Height = 0 and RawPixels = nil.

Change size (Width and Height and Depth). Previous pixel contents (RawPixels) are lost, and the contents of new pixels are undefined.

Use other method, like Resize, if you want to change image size preserving it's contents.

Size of TPixel in bytes for this TCastleImage descendant.

Size of image contents in bytes.

Warning: this symbol is deprecated.

Deprecated name for ImageSize.

Number of color components in TPixel.

E.g. RGB is 3 components and RGB+Alpha is 4 components, RGB+Exponent is 3 components (because it describes only Red, Green and Blue values (Exponent value is just used to correctly interpret these, it's not a 4th component)).

Pointer to the (x, y, z) pixel of image.

Note that they don't check X, Y, Z correctness in any way, it's your responsibility to always pass 0 <= X < Width and 0 <= Y < Height and 0 <= Z < Depth.

Note that this function should be reintroduced in descendants to return the same value but typecasted to something better then Pointer (something like ˆTPixel).

Pointer to the first pixel in the Y row of the image. Same thing as PixelPtr but always with X = 0.

Note that this function should be reintroduced in descendants to return the same value but typecasted to something better then Pointer, preferably something like ˆ(array of TPixel).

Inverts all colors (RGB or grayscale, but doesn't touch alpha channel). "Inverting" means changing color C in range [0..1] to 1-C, so black becomes white, white becomes black etc.

For descendants implementors: Override it if necessary, otherwise the default implementation in this class will raise EInternalError.

Warning: this symbol is deprecated: use Colors[X, Y, 0] to get or set colors

Create a new image object that has exactly the same class and the same data (size, pixels) as this image.

(Design note: this function is *not* a constructor, because it's implemented in TCastleImage, but it always returns some descendant of TCastleImage.)

Create a new image object that has exactly the same class and the same data (size, pixels) as this image.

Equivalent to MakeCopy, but virtual and declared as returning TEncodedImage class.

Change Width and Height and appropriately stretch image contents.

If ResizeWidth or ResizeHeight is 0 then it means to take Width or Height, respectively. So e.g. using ResizeWidth = ResizeHeight = 0 is the same thing as using ResizeWidth = Width and ResizeHeight = Height and this is NOP.

Remember that resizing may change RawPixels pointer, so all pointers that you aquired using functions like RawPixels, Pixels, PixelsArray, RowPtr, PixelPtr may be invalid after calling Resize.

Warning: this symbol is deprecated: This method is seldom useful, and it is confused with TCastleImage.DrawFrom3x3 and TDrawableImage.Draw3x3 too often. Please report if you have a use-case when this method is useful, otherwise it may get removed from the engine one day.

Change Width and Height and appropriately stretch image contents.

This scales the image in almost the same way as standard Resize. However, this is aware of the image corners and edges, which is good if you plan to use this image with TDrawableImage.Draw3x3 drawing.

The Corners parameter specifies the corners size, in the same clockwise order as for TDrawableImage.Draw3x3: top, right, bottom, left. The corners will be scaled (proportially to image scaling), and new Corners size returned. Additionally it makes sure that filtering (especially bilinear) does not "leak" colors from one image area to another. Effectively, the image is scaled like a 9 separate parts, and colors cannot bleed from one part to another.

Both ResizeWidth, ResizeHeight parameters must be provided and non-zero.

For now, only a subset of TResizeInterpolation values are supported by this method, namely the ones in TResizeInterpolationInternal.

Create a new TCastleImage instance with size ResizeWidth, ResizeHeight and pixels copied from the input and appropriately stretched. The exact class of the new instance is the same as our class.

As with Resize method, when the parameter ResizeTo* is 0 it means to use current Width/Height. So e.g. using MakeResized(0, 0) is the same thing as using CreateCopy.

Mirror image horizotally (that is right edge is swapped with left edge).

Mirror image vertically.

Make rotated version of the image. See Rotate for description of parameters.

Rotate image by Angle * 90 degrees, clockwise. For example, 0 does nothing. 1 rotates by 90 degrees, 2 rotates by 180, 3 rotates by 270. All other values (negative too) are circular (modulo), so e.g. 4 again does nothing, 5 rotates by 90 degrees and so on.

Create a new instance with the same class, and size TileX * Width and TileY * Height and contents being our contents duplicated (tiled). Must be TileX, TileY > 0.

Extract rectangular area of this image. X0 and Y0 are start position (lower-left corner), ExtractWidth, ExtractHeight specify size of area.

This checks parameters for correctness – if start position is not correct or ExtractWidth/Height are too large then exception EImagePosOutOfRange is raised.

Set all image pixels to the same color.

Check do all image pixels have the same color.

Multiply each RGB color by a matrix. This is a useful routine for many various conversions of image colors. Every pixel's RGB color is multiplied by given Matrix, i.e. PixelRGBColor := Matrix * PixelRGBColor.

If some value in some channel will be < 0, it will be set to 0. And if it will be > High(Byte), it will be set to High(Byte).

Examples: when Matrix = TMatrix3.Identity, this is NOOP. Matrix = ((2, 0, 0), (0, 1, 0), (0, 0, 1)) red channel is made lighter. Matrix = ((0, 0, 1), (0, 1, 0), (1, 0, 0)) swaps red and blue channel. Matrix = ((0.33, 0.33, 0.33), (0.33, 0.33, 0.33), (0.33, 0.33, 0.33)) is a simple conversion to grayscale (actually incorrect, even if often visually acceptable; actually instead of 0.33 one has to use GrayscaleFloat/ByteValues, this is already implemented in ImageTransformColorsVar function)

Note: it's often more optimal to hard-code necessary color transformations as TColorModulatorFunc and use ModulateRGB.

This function is only implemented for images that represent Pixel as RGB values, for now this means TRGBImage and TRGBAlphaImage. In case of TRGBAlphaImage (or any other class that represents colors as RGB + something more) alpha channel (i.e. "something more") is ignored (i.e. left without any modification).

In this class this simply raises EInternalError to say 'not implemented'. This also means that you must not call inherited in descendants when overriding this method.

Process each pixel by given function. If ColorModulator = nil then this procedure does nothing. Else, every RGB color value of an image will be transformed using ColorModulator.

Like TransformRGB: This function is only implemented for images that represent Pixel as RGB values, for now this means TRGBImage and TRGBAlphaImage. In case of TRGBAlphaImage (or any other class that represents colors as RGB + something more) alpha channel (i.e. "something more") is ignored (i.e. left without any modification).

In this class this simply raises EInternalError to say 'not implemented'. This also means that you must not call inherited in descendants when overriding this method.

Just like ModulateRGB, but this returns new image, not changing initial image. This means that if ColorModulator = nil this is equivalent to CreateCopy.

Implemented if and only if ModulateRGB is implemented.

Convert image colors to grayscale.

Implemented if and only if ModulateRGB is implemented. When image has alpha channel, alpha channel value (or just anything beyond 3 rgb components) is ignored (not modified).

This changes color to grayscale, but format of memory storage is the same. For example, for TRGBImage, they are still kept in RGB format (just Red = Green = Blue). If you want to convert to true Grayscale format, you should use TRGBImage.ToGrayscale that will create new TGrayscaleImage instance.

Convert every image color using Color*Convert function from CastleVectors. "Channel" parameter determines which Color*Convert function to use (Red, Green or Blue), must be 0, 1 or 2.

Implemented if and only if ModulateRGB is implemented.

Converts every image color using Color*Strip function from CastleVectors. "Channel" parameter determines which Color*Strip function to use (Red, Green or Blue), must be 0, 1 or 2.

Implemented if and only if ModulateRGB is implemented.

Check if given Image has the same class, the same sizes (Width, Height) and contains exactly the same pixel values.

This is like IsEqual, but is compares only given parts of the images. Note that it's your responsibility to make sure that given areas are really within the sizes of Self or Image.

Overloaded version without SelfXxx parameters compares whole Self to given part of Image. Analogously, version without ImageXxx parameters compares whole Image to part of Self.

Draw one image part on another image. X, Y is the lower-left position on the destination image where we draw. Optional SourceX, SourceY, SourceWidth, SourceHeight specify to use only a part of the source image (without them, we take whole source image). The pixel on source image (SourceX, SourceY) will be drawn on destination image on (X, Y).

The coordinates and sizes are carefully checked, so that we do not try to take some pixels outside of the source or destination image.

Warning: It is not efficient to use this drawing method. This drawing is performed on CPU and cannot be fast. If possible, use instead TDrawableImage.DrawFrom, that performs image-on-image drawing using GPU, or just draw TDrawableImage straight to the screen by TDrawableImage.Draw. See examples/images_videos/draw_images_on_gpu.lpr for an example of TDrawableImage.DrawFrom. Using this method makes most sense in image manipulation tools, or during the loading / preparation stage of your game, not during actual game.

Note for descendants implementors: The default implementation of this function in TCastleImage can only directly copy the pixels, regardless of what information they have. This makes it very fast, but not suitable if the source image has some alpha channel and you want to apply it over a destination image with blending (adding scaled source to a destination color), and not suitable when Mode is <> dmBlend. Descendants with alpha channel should override DrawFromCore to handle drawing with blending (for dmBlend), all descendants should override DrawFromCore to handle drawing with Mode <> dmBlend.

Exceptions raised

EImageDrawError

When drawing cannot be performed, for example because drawing with this Mode, and/or for this Source and destination classes, is not implemented yet.

Draw the Source image on this image, dividing the source image into 3x3 parts for corners, sides, and inside.

The source image is divided into 3 * 3 = 9 parts:

• 4 corners, used to fill the corners of the DestinationRect. They are not stretched.

• 4 sides, used to fill the sides of the DestinationRect between the corners. They are scaled in one dimension, to fill the space between corners completely.

• the inside. Used to fill the rectangular inside. Scaled in both dimensions as necessary.

The size of corners is specified in the SourceCorners parameter, in the order: top, right, bottom, left. (It's the same order as e.g. CSS margins.)

Warning: It is not efficient to use this drawing method. This drawing is performed on CPU and cannot be fast. If possible, use instead TDrawableImage, and either draw it to the screen by TDrawableImage.Draw3x3, or draw it to another TDrawableImage by combining TDrawableImage.Draw3x3 with TDrawableImage.RenderToImageBegin. Using this method makes most sense in image manipulation tools, or during the loading / preparation stage of your game, not during actual game.

Makes linear interpolation of colors from this image and the SecondImage. Intuitively, every pixel in new image is set to

(1 - Value) * Self[pixel] + Value * SecondImage[pixel]

Both images need to have the exact same size. If they are not, EImageLerpDifferentSizes is raised.

Not all TCastleImage combinations are allowed. Every subclass is required to override this to at least handle Lerp between itself. That is, TRGBImage.Lerp has to handle Lerp with other TRGBImage, TRGBAlphaImage.Lerp has to handle Lerp with other TRGBAlphaImage etc. Other combinations may be permitted, if useful and implemented. EImageLerpInvalidClasses is raised if given class combinations are not allowed.

In this class, this simply always raises EImageLerpInvalidClasses.

Exceptions raised

EImageLerpDifferentSizes

When SecondImage size differs from this image.

EImageLerpInvalidClasses

When Lerp between this TCastleImage descendant class and SecondImage class is not implemented.

Mix 4 colors, with 4 weights, into a resulting color. All 4 Colors and OutputColor must be pointers to a pixel of current image class, that is they must point to PixelSize bytes of memory.

Exceptions raised

EImageLerpInvalidClasses

When mixing is not implemented for this image class.

Copy size and contents from Source. This sets our size (Width, Height and Depth) to match Source image, and copies pixels from the Source image, converting them as closely as possible. For example, converting RGBA to RGB will strip alpha channel, but copy RGB values.

When implementing descendants: the base implementation of this method in TCastleImage handles only the case when Image class equals our own class. And raises EImageAssignmentError in other cases. Override this method if you want to actually handle some conversions when assignning.

Exceptions raised

EImageAssignmentError

If it's not possible to convert from Source class to us.

Append code to embed this image inside Pascal source code.

Set the RGB colors for transparent pixels to the nearest non-transparent colors. This fixes problems with black/white borders around the texture regions, when the texture is scaled down (by any means – on CPU, during rendering on GPU...).

The algorithm implemented here, for now, is really slow (but also really correct). It should only be used as a last resort, when your normal tool (like Spine atlas packer) cannot do a decent job on a given image. You should use this when creating assets, and save the resulting image to disk (avoid doing this at runtime during the game, since it's really really slow).

Draw simple geometric shapes like circles, rectangles, lines, etc.

Get or set the color of the pixel.

In case of descendants without alpha, we may drop this information.

In case of grayscale descendants, when getting or setting we convert the color to/from grayscale as necessary. This means that setting RGB color on a grayscale image may lose information – we will convert your color to grayscale.

Caller is responsible for checking the correctness of given X, Y, Z coordinates. For speed, we may not check them inside (so nasty memory errors will occur in case of invalid coordinates).