Image

Image type. Image has disabled copy ctor and postblit, to avoid accidental allocations.

IMPORTANT

Images are subtyped like this:

Image Images can be: isError() or isValid(). / \ Image start their life as Image.init in error state. isError() or isValid() Image that are isValid have a known PixelType, unlike isError images. / \ hasData() or !hasData() Images that have a type can have a data pointer or not. If it has no type, it implicitely has no data, and asking if it has data is forbidden. Also: isOwned() exist for image that are hasData(). Only image with hasData() have to follow the LayoutConstraints, though all image have a LayoutConstraints.

is8Bit or is16Bit or isFP32 Image components can be stored in 8-bit ubyte, 16-bit ushort, or float \____ | ______/ \ | / isValid() ___/ | \______ Planar and compressed images are not implemented yet, so it's only / | \ "plain pixels" for now. isPlanar or isPlainPixels or isCompressed Also: hasNonZeroSize(). Images with a type have a width and height and a layer count (and any of this can be zero!).

isValid() ___/ | \______ Images can have several "layers", each of them is a consecutive 2D image. / | \ This is for animated image support. hasZerolayer or hasOneLayer or hasMultipleLayers Similar to OpenGL 2D array textures. | V (most typical case is 1 layer)

More...

nothrow @nogc @safe

struct Image {

int pitchInBytes();

int layerOffsetInBytes();

int scanlineInBytes();

bool isStoredUpsideDown();

inout(void)* scanptr(int y);

inout(void)[] scanline(int y);

inout(void)[] layerline(int layer, int y);

inout(ubyte)[] allPixelsAtOnce();

float dotsPerInchX();

float dotsPerInchY();

float pixelAspectRatio();

float pixelsPerMeterX();

float pixelsPerMeterY();

alias errored = isError;

bool isValid();

const(char)[] errorMessage();

ubyte* disownData();

alias hasPlainPixels = isPlainPixels;

bool isPlanar();

bool isCompressed();

bool hasNonZeroSize();

bool hasZeroLayer();

bool hasSingleLayer();

bool hasMultipleLayers();

this(int width, int height, PixelType type, LayoutConstraints layoutConstraints);

void create(int width, int height, PixelType type, LayoutConstraints layoutConstraints);

void createLayered(int width, int height, int layers, PixelType type, LayoutConstraints layoutConstraints);

void createNoInit(int width, int height, PixelType type, LayoutConstraints layoutConstraints);

void createLayeredNoInit(int width, int height, int layers, PixelType type, LayoutConstraints layoutConstraints);

alias setSize = createNoInit;

Image layer(int layerIndex);

const(Image) layer(int layerIndex);

Image layerRange(int layerStart, int layerEnd);

const(Image) layerRange(int layerStart, int layerEnd);

void createViewFromData(void* data, int width, int height, PixelType type, int pitchInBytes);

void createLayeredViewFromData(void* data, int width, int height, int layers, PixelType type, int pitchInBytes, int layerOffsetBytes);

void createWithNoData(int width, int height, PixelType type, LayoutConstraints layoutConstraints);

void createLayeredWithNoData(int width, int height, int layers, PixelType type, LayoutConstraints layoutConstraints);

Image clone();

void copyPixelsTo(Image img);

bool loadFromFile(const(char)[] path, int flags);

bool loadFromMemory(const(ubyte)[] bytes, int flags);

bool loadFromMemory(const(void)[] bytes, int flags);

bool loadFromStream(IOStream io, IOHandle handle, int flags);

bool saveToFile(const(char)[] path, int flags);

bool saveToFile(ImageFormat fif, const(char)[] path, int flags);

ubyte[] saveToMemory(ImageFormat fif, int flags);

bool saveToStream(ImageFormat fif, IOStream io, IOHandle handle, int flags);

static ImageFormat identifyFormatFromFile(const(char)* filename);

static ImageFormat identifyFormatFromMemory(const(ubyte)[] bytes);

static ImageFormat identifyFormatFromStream(IOStream io, IOHandle handle);

static ImageFormat identifyFormatFromFileName(const(char)* filename);

LayoutConstraints layoutConstraints();

alias changeLayout = setLayout;

bool convertToGreyscale(LayoutConstraints layoutConstraints);

bool convertToGreyscaleAlpha(LayoutConstraints layoutConstraints);

bool convertToRGB(LayoutConstraints layoutConstraints);

bool convertToRGBA(LayoutConstraints layoutConstraints);

bool addAlphaChannel(LayoutConstraints layoutConstraints);

bool dropAlphaChannel(LayoutConstraints layoutConstraints);

bool convertTo8Bit(LayoutConstraints layoutConstraints);

bool convertTo16Bit(LayoutConstraints layoutConstraints);

bool convertToFP32(LayoutConstraints layoutConstraints);

bool convertTo(PixelType targetType, LayoutConstraints layoutConstraints);

bool castTo(PixelType targetType);

int scanlineAlignment();

int borderWidth();

int pixelMultiplicity();

int trailingPixels();

bool isGapless();

bool mustBeStoredUpsideDown();

bool mustNotBeStoredUpsideDown();

bool flipHorizontal();

bool flipVertical();

~this();

}

Constructors

this this(int width, int height, PixelType type, LayoutConstraints layoutConstraints): Clear the image, and creates a new owned image, with given dimensions and plain pixels. The image data is cleared with zeroes. Tags: none.

Destructor

~this ~this(): Destructor. Everything is reclaimed.

Postblit

A postblit is present on this object, but not explicitly documented in the source.

Members

Aliases

changeLayout deprecated alias changeLayout = setLayout: Keep the same pixels and type, but change how they are arranged in memory to fit some constraints. Tags: #valid
errored deprecated alias errored = isError: The image is unusable and has no known PixelType, nor any data pointed to. You can reach this state with OOM, failing to load a source image, etc. Always return !isError(). Tags: none.
hasPlainPixels deprecated alias hasPlainPixels = isPlainPixels: A plain pixel image is for example rgba8, and has scanline() access. Currently only one supported. Tags: #valid.
setSize alias setSize = createNoInit: Clear the image, and creates a new owned image, with given dimensions and plain pixels. The image data is left uninitialized, so it may contain data from former allocations. Tags: none.

Functions

addAlphaChannel bool addAlphaChannel(LayoutConstraints layoutConstraints): Add an opaque alpha channel if not-existing already. Tags: #valid
allPixelsAtOnce inout(ubyte)[] allPixelsAtOnce(): Returns a slice of all pixels OF ALL LAYERS at once in O(1). This is only possible if the image is stored non-flipped, and without space between scanlines and layers. To avoid accidental correctness, the image NEEDS to have the layout constraints: LAYOUT_GAPLESS | LAYOUT_VERT_STRAIGHT. Tags: #valid #data #plain
borderWidth int borderWidth(): Get the number of border pixels around the image. This is an area that can be safely accessed, using -pitchInBytes() and pointer offsets. The actual border width could well be higher, but there is no way of safely knowing that.
castTo bool castTo(PixelType targetType): Reinterpret cast the image content. For example if you want to consider a RGBA8 image to be uint8, but with a 4x larger width. This doesn't allocates new data storage.
clearError void clearError(): Clear the error, if any. This is only for use inside Gamut. Each operations that "recreates" the image, such a loading, clear the existing error and leave the Image in a clean-up state.
clone Image clone(): Clone an existing image. This image should have plain pixels. Tags: #valid #data #plain.
convertTo bool convertTo(PixelType targetType, LayoutConstraints layoutConstraints): Convert the image to the following format. This can destruct channels, loose precision, etc. You can also change the layout constraints at the same time.
convertTo16Bit bool convertTo16Bit(LayoutConstraints layoutConstraints): Convert the image bit-depth to 16-bit per component. Tags: #valid.
convertTo8Bit bool convertTo8Bit(LayoutConstraints layoutConstraints): Convert the image bit-depth to 8-bit per component. Tags: #valid
convertToFP32 bool convertToFP32(LayoutConstraints layoutConstraints): Convert the image bit-depth to 32-bit float per component. Tags: #valid.
convertToGreyscale bool convertToGreyscale(LayoutConstraints layoutConstraints): Convert the image to greyscale, using a greyscale transformation (all channels weighted equally). Alpha is preserved if existing. Tags: #valid
convertToGreyscaleAlpha bool convertToGreyscaleAlpha(LayoutConstraints layoutConstraints): Convert the image to a greyscale + alpha equivalent, using duplication and/or adding an opaque alpha channel. Tags: #valid
convertToRGB bool convertToRGB(LayoutConstraints layoutConstraints): Convert the image to a RGB equivalent, using duplication if greyscale. Alpha is preserved if existing. Tags: #valid
convertToRGBA bool convertToRGBA(LayoutConstraints layoutConstraints): Convert the image to a RGBA equivalent, using duplication and/or adding an opaque alpha channel. Tags: #valid
copyPixelsTo void copyPixelsTo(Image img): Copy pixels to an image with same size and type. Both images should have plain pixels. Tags: #valid #data #plain.
create void create(int width, int height, PixelType type, LayoutConstraints layoutConstraints)
createLayered void createLayered(int width, int height, int layers, PixelType type, LayoutConstraints layoutConstraints): Clear the image, and creates a new owned image, with given dimensions and plain pixels. The image data is cleared with zeroes. Tags: none.
createLayeredNoInit void createLayeredNoInit(int width, int height, int layers, PixelType type, LayoutConstraints layoutConstraints): Clear the image, and creates a new owned image, with given dimensions and plain pixels. The image data is left uninitialized, so it may contain data from former allocations. Tags: none.
createLayeredViewFromData void createLayeredViewFromData(void* data, int width, int height, int layers, PixelType type, int pitchInBytes, int layerOffsetBytes): Create a view into existing data. The image data is considered read/write, and not owned. No layout constraints are assumed. The input scanlines must NOT overlap.
createLayeredWithNoData void createLayeredWithNoData(int width, int height, int layers, PixelType type, LayoutConstraints layoutConstraints): Initialize an image with no data, for example if you wanted an image without the pixel content. Tags: none.
createNoInit void createNoInit(int width, int height, PixelType type, LayoutConstraints layoutConstraints): Clear the image, and creates a new owned image, with given dimensions and plain pixels. The image data is left uninitialized, so it may contain data from former allocations. Tags: none.
createViewFromData void createViewFromData(void* data, int width, int height, PixelType type, int pitchInBytes): Create a view into existing data. The image data is considered read/write, and not owned. No layout constraints are assumed. The input scanlines must NOT overlap.
createWithNoData void createWithNoData(int width, int height, PixelType type, LayoutConstraints layoutConstraints): Initialize an image with no data, for example if you wanted an image without the pixel content. Tags: none.
disownData ubyte* disownData(): Disown the image allocation data. This return both the pixel _data (same as and the allocation data The data MUST be freed with freeImageData. The image still points into that data, and you must ensure the data lifetime exceeeds the image lifetime. Tags: #valid #own #data Warning: this return the malloc'ed area, NOT the image data itself. However, with the constraints
dotsPerInchX float dotsPerInchX()
dotsPerInchY float dotsPerInchY()
dropAlphaChannel bool dropAlphaChannel(LayoutConstraints layoutConstraints): Removes the alpha channel if not-existing already. Tags: #valid
error void error(const(char)[] msg): Set the image in an errored state, with msg as a message. Note: msg MUST be zero-terminated.
errorMessage const(char)[] errorMessage(): The error message (null if no error currently held). This slice is followed by a '\0' zero terminal character, so it can be safely given to print. Tags: none.
flipHorizontal bool flipHorizontal(): Flip the image data horizontally. If the image has no data, the operation is successful. Tags: #valid.
flipVertical bool flipVertical(): Flip the image vertically. If the image has no data, the operation is successful.
hasData bool hasData(): An image can have data (usually pixels), or not. "Data" refers to pixel content, that can be in a decoded form, but also in more complicated forms such as planar, compressed, etc. (FUTURE)
hasMultipleLayers bool hasMultipleLayers(): Animated images have more. Tags: #valid.
hasNonZeroSize bool hasNonZeroSize(): An image for which width > 0 and height > 0. Tags: none.
hasSingleLayer bool hasSingleLayer(): Typical images have one layer. Tags: #valid.
hasType deprecated bool hasType(): An image can have a pixel type (usually pixels), or not. Not a lot of operations are available if there is no type. Note: An image that has no must necessarily have no data. Tags: none.
hasZeroLayer bool hasZeroLayer(): An image is allowed to have zero layers, in which case it is considered much like having zero width or zero height. Tags: #valid.
height int height()
is16Bit bool is16Bit(): Is the image type represented by 16-bit components? Tags: #valid.
is8Bit bool is8Bit(): Is the image type represented by 8-bit components? Tags: #valid.
isCompressed bool isCompressed(): A compressed image doesn't have its pixels available. Currently not supported. Tags: #valid.
isFP32 bool isFP32(): Is the image type represented by 32-bit floating point components? Tags: #valid.
isGapless bool isGapless(): Get if being gapless is guaranteed by the layout constraints. Note that this only holds if there is some data in the first place.
isOwned bool isOwned(): An that has data can own it (will free it in destructor) or can borrow it. An image that has no data, cannot own it. Tags: none.
isPlanar bool isPlanar(): A planar image is for example YUV420. If the image is planar, its rows are not accessible like that. Currently not supported. Tags: #valid.
isStoredUpsideDown bool isStoredUpsideDown(): A compressed image doesn't have its pixels available. Warning: only makes sense for image that hasData(), with non-zero height. Tags: #valid #data
isValid bool isValid(): Im ge is valid, meaning it is not in error state. Always return !isError(). Tags: none.
layer Image layer(int layerIndex)
const(Image) layer(int layerIndex): Return a view into an existing image layer. The image data is considered read/write, and NOT OWNED. TODO: preserve some layout constraints. In case of errors, the returned Image is invalid. Tags: #valid #data
layerOffsetInBytes int layerOffsetInBytes(): Get the layer offset (byte distance between successive layers), in bytes.
layerRange Image layerRange(int layerStart, int layerEnd)
const(Image) layerRange(int layerStart, int layerEnd): Return a view into an existing image layer. The image data is considered read/write, and NOT OWNED. TODO: preserve some layout constraints. In case of errors, the returned Image is invalid. Tags: #valid #data
layerline inout(void)[] layerline(int layer, int y): Returns a slice to the y nth line of pixels, in the given layer. scanline is a shortcut to index the first layer (layer index 0). Only possible if the image has plain pixels. What pixel format it points to, depends on the image type().
layers int layers()
layoutConstraints LayoutConstraints layoutConstraints(): Get the image layout constraints. Tags: none.
loadFromFile bool loadFromFile(const(char)[] path, int flags): Load an image from a file location.
loadFromMemory bool loadFromMemory(const(ubyte)[] bytes, int flags)
bool loadFromMemory(const(void)[] bytes, int flags): Load an image from a memory location.
loadFromStream bool loadFromStream(IOStream io, IOHandle handle, int flags): Load an image from a set of user-defined I/O callbacks.
mustBeStoredUpsideDown bool mustBeStoredUpsideDown()
mustNotBeStoredUpsideDown bool mustNotBeStoredUpsideDown()
pitchInBytes int pitchInBytes(): Get the image pitch (byte distance between rows), in bytes.
pixelAspectRatio float pixelAspectRatio()
pixelMultiplicity int pixelMultiplicity(): Get the multiplicity of pixels in a single scanline. The actual multiplicity could well be higher.
pixelsPerMeterX float pixelsPerMeterX()
pixelsPerMeterY float pixelsPerMeterY()
saveToFile bool saveToFile(const(char)[] path, int flags): Saves an image to a file, detecting the format from the path extension.
saveToFile bool saveToFile(ImageFormat fif, const(char)[] path, int flags): Save the image into a file, with a given file format.
saveToMemory ubyte[] saveToMemory(ImageFormat fif, int flags): Saves the image into a new memory location. The returned data must be released with a call to freeEncodedImage.
saveToStream bool saveToStream(ImageFormat fif, IOStream io, IOHandle handle, int flags): Save an image with a set of user-defined I/O callbacks.
scanline inout(void)[] scanline(int y): Returns a slice to the y nth line of pixels, in the given layer. scanline is a shortcut to index the first layer (layer index 0). Only possible if the image has plain pixels. What pixel format it points to, depends on the image type().
scanlineAlignment int scanlineAlignment(): On how many bytes each scanline is aligned. Useful to know for SIMD. The actual alignment could be higher than what the layout constraints strictly tells.
scanlineInBytes int scanlineInBytes(): Length of the managed scanline pixels, in bytes.
scanptr inout(void)* scanptr(int y): Returns a scanline pointer to the y nth line of pixels, in the given layer. scanptr is a shortcut to index the first layer (layer index 0). Only possible if the image has plain pixels. What pixel format it points to, depends on the image type().
trailingPixels int trailingPixels(): Get the guaranteed number of scanline trailing pixels, from the layout constraints. Each scanline is followed by at least that much out-of-image pixels, that can be safely READ. The actual number of trailing pixels can well be larger than what the layout strictly tells, but we'll never know.
type PixelType type(): Get the pixel type.
width int width()

Static functions

identifyFormatFromFile ImageFormat identifyFormatFromFile(const(char)* filename): Identify the format of an image by minimally reading it. Read first bytes of a file to identify it. You can use a filename, a memory location, or your own IOStream.
identifyFormatFromFileName ImageFormat identifyFormatFromFileName(const(char)* filename): Identify the format of an image by looking at its extension.
identifyFormatFromMemory ImageFormat identifyFormatFromMemory(const(ubyte)[] bytes)
identifyFormatFromStream ImageFormat identifyFormatFromStream(IOStream io, IOHandle handle): Identify the format of an image by minimally reading it. Read first bytes of a file to identify it. You can use a filename, a memory location, or your own IOStream.

Variables

_allocArea ubyte* _allocArea;: Pointer to the malloc area holding the data. _allocArea being null signify that there is no data, or that the data is borrowed. _allocArea not being null signify that the image is owning its data.
_data ubyte* _data;: Pointer to the pixel data. What is pointed to depends on _type. The amount of what is pointed to depends upon the dimensions. it is possible to have _data null but _type is known.
_error const(char)* _error;: Pointer to last known error. null means "no errors". Once an error has occured, continuing to use the image is Undefined Behaviour. Must be zero-terminated. By default, a T.init image is errored().
_height int _height;: Height of the image in pixels, when pixels makes sense. By default, this height is 0 (but as the image has no pixel data, this doesn't matter).
_layerCount int _layerCount;: Number of layers of the image. A normal image has typically 1 layer, animated image have more.
_layerOffset int _layerOffset;: Pitch in bytes between successive layers. All layers have same dimension and constraints and type. Always >= 0, unlike _pitch.
_layoutConstraints LayoutConstraints _layoutConstraints;: The data layout constraints, in flags.
_pitch int _pitch;: Pitch in bytes between lines, when a pitch makes sense. This pitch can be, or not be, a negative integer. When the image has layout constraint LAYOUT_VERT_FLIPPED, it is always kept <= 0. When the image has layout constraint LAYOUT_VERT_STRAIGHT, it is always kept >= 0.
_pixelAspectRatio float _pixelAspectRatio;: Pixel aspect ratio. https://en.wikipedia.org/wiki/Pixel_aspect_ratio
_resolutionY float _resolutionY;: Physical image resolution in vertical pixel-per-inch.
_type PixelType _type;: The type of the data pointed to.
_width int _width;: Width of the image in pixels, when pixels makes sense. By default, this width is 0 (but as the image has no pixel data, this doesn't matter).

Detailed Description

IMPORTANT: there is no constness in Image. All Image are considered read/write, with no const concept.

Public Functions are labelled this way: #valid => the calling Image must have a type (ie. not in error state). #data => the calling Image must have data (requires #valid) #plain => the calling Image must have plain-pixels. #own => the calling Image must have data AND own it. It is a programming error to call a function that doesn't follow the tag constraints (will assert)

The OpenD Programming Language