Class TGrayscaleImage

This item has no description.

Source: images/castleimages.pas (line 188).

Size of image contents in bytes.

Source: images/castleimages.pas (line 227).

Get a 3D vector with Width, Height, Depth.

Source: images/castleimages.pas (line 230).

Is an image empty.

True means that RawPixels = Nil, and Width * Height * Depth = 0 (so either Width = 0 or Height = 0 or Depth = 0).

False means that RawPixels <> nil and Width * Height * Depth <> 0 (so all Width > 0 and Height > 0 and Depth > 0, since they are Cardinal (unsigned) always).

Source: images/castleimages.pas (line 241).

Does an image have an alpha channel.

You may also be interested in the AlphaChannel that can make a distinction between alpha channel for blending and for alpha test. AlphaChannel answers always atNone if HasAlpha = false, and always acTest or acBlending if HasAlpha = true. But AlphaChannel may perform longer analysis of pixels (to differ between acTest and acBlending), while this function always executes ultra-fast (as it's constant for each TCastleImage descendant).

Descendants implementors notes: in this class, TCastleImage, this returns False. Override to return True for images with alpha channel.

Source: images/castleimages.pas (line 257).

Analyze image contents to determine if, and what kind, of alpha channel it has.

This may be a time-consuming operation. When the image has alpha channel and we need to decide whether it's suitable for "alpha test" (only fully opaque or fully transparent pixels) or "alpha blending" (any alpha value makes sense) then this method needs to iterate over image pixels.

For this reason, the result of this operation is cached at various levels, e.g. TImageTextureNode and TDrawableImage cache it internally.

We determine "alpha test - simple yes/no alpha channel" if all the alpha values (for every pixel) are 0, or 255, or (when AlphaTolerance <> 0) are close to them by AlphaTolerance. So, to be precise, alpha value must be <= AlphaTolerance, or >= 255 - AlphaTolerance. If any alpha value is between [AlphaTolerance + 1, 255 - AlphaTolerance - 1] then we return "alpha blending - full range alpha channel".

Note that big values of AlphaTolerance make it easier to quality image as "alpha test - simple yes/no alpha channel". When AlphaTolerance >= 128, all images are treated as "simple yes/no alpha". Usually, you want to keep AlphaTolerance small.

Descendants implementors notes: in this class, this simply always returns atNone. For descendants that have alpha channel, implement it, honouring AlphaTolerance as described.

Source: images/castleimages.pas (line 286).

Rectangle representing the inside of this image. Always (Left,Bottom) are zero, and (Width,Height) correspond to image sizes.

Source: images/castleimages.pas (line 293).

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

Source: images/castleimages.pas (line 297).

Mirror image vertically.

Source: images/castleimages.pas (line 300).

Warning: this symbol is deprecated: interoperability with FpImage may be dropped in the future

Convert image contents to FpImage instance. The resulting instance is owned by the caller.

Source: images/castleimages.pas (line 305).

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

Source: images/castleimages.pas (line 508).

This item has no description.

Source: images/castleimages.pas (line 509).

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

Source: images/castleimages.pas (line 513).

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.

Source: images/castleimages.pas (line 521).

This item has no description.

Source: images/castleimages.pas (line 524).

Size of TPixel in bytes for this TCastleImage descendant.

Source: images/castleimages.pas (line 527).

Size of image contents in bytes.

Source: images/castleimages.pas (line 530).

Warning: this symbol is deprecated.

Deprecated name for ImageSize.

Source: images/castleimages.pas (line 533).

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

Source: images/castleimages.pas (line 541).

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

Source: images/castleimages.pas (line 552).

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

Source: images/castleimages.pas (line 560).

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.

Source: images/castleimages.pas (line 569).

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

This item has no description.

Source: images/castleimages.pas (line 594).

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

Source: images/castleimages.pas (line 602).

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.

Source: images/castleimages.pas (line 608).

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.

Source: images/castleimages.pas (line 622).

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.

Source: images/castleimages.pas (line 644).

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.

Source: images/castleimages.pas (line 656).

Mirror image horizontally (that is, the right edge is swapped with the left edge).

Source: images/castleimages.pas (line 660).

Mirror image vertically.

Source: images/castleimages.pas (line 663).

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

Source: images/castleimages.pas (line 667).

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.

Source: images/castleimages.pas (line 673).

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.

Source: images/castleimages.pas (line 679).

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.

Source: images/castleimages.pas (line 688).

Set all image pixels to the same color.

Source: images/castleimages.pas (line 691).

This item has no description.

Source: images/castleimages.pas (line 692).

Check do all image pixels have the same color.

Source: images/castleimages.pas (line 695).

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.

Source: images/castleimages.pas (line 731).

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.

Source: images/castleimages.pas (line 748).

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.

Source: images/castleimages.pas (line 755).

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.

Source: images/castleimages.pas (line 769).

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.

Source: images/castleimages.pas (line 776).

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.

Source: images/castleimages.pas (line 783).

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

Source: images/castleimages.pas (line 787).

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.

Source: images/castleimages.pas (line 798).

This item has no description.

Source: images/castleimages.pas (line 803).

This item has no description.

Source: images/castleimages.pas (line 807).

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.

Source: images/castleimages.pas (line 853).

This item has no description.

Source: images/castleimages.pas (line 855).

This item has no description.

Source: images/castleimages.pas (line 858).

This item has no description.

Source: images/castleimages.pas (line 861).

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.

Source: images/castleimages.pas (line 895).

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.

Source: images/castleimages.pas (line 924).

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.

Source: images/castleimages.pas (line 932).

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.

Source: images/castleimages.pas (line 951).

Append code to embed this image inside Pascal source code.

Source: images/castleimages.pas (line 954).

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

Source: images/castleimages.pas (line 971).

This item has no description.

Source: images/castleimages.pas (line 972).

Warning: this symbol is deprecated: do not use TCastleImage drawing; use other libraries (like FpImage or Vampyre Imaging or BGRABitmap) or our TDrawableImage (use RenderToImageBegin/End, and DrawCircle/DrawCircleOutline to draw ellipses using GPU)

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

Source: images/castleimages.pas (line 977).

Warning: this symbol is deprecated: do not use TCastleImage drawing; use other libraries (like FpImage or Vampyre Imaging or BGRABitmap) or our TDrawableImage (use RenderToImageBegin/End, and DrawCircle/DrawCircleOutline to draw ellipses using GPU)

This item has no description.

Source: images/castleimages.pas (line 980).

Warning: this symbol is deprecated: do not use TCastleImage drawing; use other libraries (like FpImage or Vampyre Imaging or BGRABitmap) or our TDrawableImage (use RenderToImageBegin/End, and DrawRectangle/DrawRectangleOutline to draw rectangles using GPU)

This item has no description.

Source: images/castleimages.pas (line 983).

Warning: this symbol is deprecated: do not use TCastleImage drawing; use other libraries (like FpImage or Vampyre Imaging or BGRABitmap) or our TDrawableImage (use RenderToImageBegin/End, and DrawRectangle/DrawRectangleOutline to draw rectangles using GPU)

This item has no description.

Source: images/castleimages.pas (line 986).

Warning: this symbol is deprecated: do not use TCastleImage drawing; use other libraries (like FpImage or Vampyre Imaging or BGRABitmap) or our TDrawableImage (use RenderToImageBegin/End, and DrawPrimitive2D to draw lines using GPU)

This item has no description.

Source: images/castleimages.pas (line 989).

Warning: this symbol is deprecated: do not use TCastleImage drawing; use other libraries (like FpImage or Vampyre Imaging or BGRABitmap) for drawing on images

This item has no description.

Source: images/castleimages.pas (line 992).

Url from which this image was loaded, if any.

Source: images/castleimages.pas (line 186).

This item has no description.

Source: images/castleimages.pas (line 190).

This item has no description.

Source: images/castleimages.pas (line 191).

Depth of the image. For 2D images (most common) this is just 1.

All images in CastleImages can be potentially 3D, which means they can have Depth > 1. A 3D image is just a 3-dimensional array of pixels, and you can use it e.g. as a texture with 3D texture coordinates. A sample use-cases for 3D textures are:

• Generated colors of some material that you can imagine as a 3D volume, like a volume of wood or marble. This is nice to apply on any complicated 3D shape, because the necessary 3D texture coordinates are trivial, since 3D position of a point on the shape can be used as a reasonable 3D texture coordinate.

• Medical data, some scans are 3D.

• Noise (like Perlin noise) used for various effects in shaders.

• Specialized noise, e.g. a volume of smoke, or a volume of clouds.

Source: images/castleimages.pas (line 215).

Image data. The layout of this memory is defined by descendants. For example, for TCastleImage it's a simple array of pixels (see TCastleImage docs for exact description of the memory layout), for TGPUCompressedImage it's a compressed data for GPU.

Note that this may be Nil, if Width * Height * Depth = 0. In this case, IsEmpty returns True.

Source: images/castleimages.pas (line 224).

Get or set the color of the pixel. The given value TCastleColor is a 4D vector representing the color RGB and "alpha" (opacity).

When setting the TCastleColor value on image descendants that don't store alpha information, we ignore the provided alpha value. For example, if you do MyImage.Colors[0, 0, 0] := Vector4(1, 1, 0, 0.5) (setting color to half-transparent yellow) but MyImage is TRGBImage, then the alpha value 0.5 will be ignored. We will only set the RGB channels, to (1,1,0), in the above example.

When reading the color for image descendants that store only grayscale color, we just replicate the grayscale value to all three RGB channels.

When setting the color for image descendants that store only grayscale color, we calculate the weighted average (see GrayscaleValue) of RGB channels provided.

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

Source: images/castleimages.pas (line 592).