Image

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

IMPORTANT

Images are subtyped like this:

Image All image can also be: errored() or not. / \ no-type or hasType() / \ hasData() or no-data Also: hasNonZeroSize(). ___/ | \______ Images with a type have a width and height (that can be zero). / | \ Also: isOwned() exist for image that are hasData(). isPlanar or hasPlainPixels or isCompressed Planar and compressed images are not implemented. Only image with hasData() have to follow the LayoutConstraints, though all image have a LayoutConstraints.

Public Functions are labelled this way: #type => the calling Image must have a type. #data => the calling Image must have data (implies #type) #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.

nothrow @nogc @safe

struct Image {

PixelType type();

int height();

int pitchInBytes();

int scanlineInBytes();

bool isStoredUpsideDown();

inout(ubyte)* scanline(int y);

inout(ubyte)[] allPixelsAtOnce();

float dotsPerInchX();

float dotsPerInchY();

float pixelAspectRatio();

float pixelsPerMeterX();

float pixelsPerMeterY();

bool errored();

const(char)[] errorMessage();

bool hasType();

bool hasData();

bool isOwned();

ubyte* disownData();

alias hasPlainPixels = isPlainPixels;

bool isPlainPixels();

bool isPlanar();

bool isCompressed();

bool hasNonZeroSize();

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

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

void initWithNoData(int width, int height, 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();

bool changeLayout(LayoutConstraints layoutConstraints);

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 flipHorizontally();

bool flipVertically();

bool flipVerticallyLogical();

bool flipVerticallyPhysical();

}

Constructors

this this(int width, int height, PixelType type, LayoutConstraints layoutConstraints): Clear the image and initialize a new image, with given dimensions and plain pixels. Tags: none.

Destructor

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

Postblit

this(this) this(this): Undocumented in source.

Members

Aliases

hasPlainPixels deprecated alias hasPlainPixels = isPlainPixels: An image can have plain pixels, which means: 1. it has data (and as such, a type) 2. those are in a plain decoded format (not a compressed texture, not planar, etc). Tags: none.

Functions

addAlphaChannel bool addAlphaChannel(LayoutConstraints layoutConstraints): Add an opaque alpha channel if not-existing already. Tags: #type
allPixelsAtOnce inout(ubyte)[] allPixelsAtOnce(): Returns a slice of all pixels at once in O(1). This is only possible if the image is stored non-flipped, and without space between scanline. To avoid accidental correctness, the image need the layout constraints: LAYOUT_GAPLESS | LAYOUT_VERT_STRAIGHT. Tags: #type #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.
changeLayout bool changeLayout(LayoutConstraints layoutConstraints): Keep the same pixels and type, but change how they are arranged in memory to fit some constraints. Tags: #type
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: #type #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: #type.
convertTo8Bit bool convertTo8Bit(LayoutConstraints layoutConstraints): Convert the image bit-depth to 8-bit per component. Tags: #type
convertToFP32 bool convertToFP32(LayoutConstraints layoutConstraints): Convert the image bit-depth to 32-bit float per component. Tags: #type.
convertToGreyscale bool convertToGreyscale(LayoutConstraints layoutConstraints): Convert the image to greyscale, using a greyscale transformation (all channels weighted equally). Alpha is preserved if existing. Tags: #type
convertToGreyscaleAlpha bool convertToGreyscaleAlpha(LayoutConstraints layoutConstraints): Convert the image to a greyscale + alpha equivalent, using duplication and/or adding an opaque alpha channel. Tags: #type
convertToRGB bool convertToRGB(LayoutConstraints layoutConstraints): Convert the image to a RGB equivalent, using duplication if greyscale. Alpha is preserved if existing. Tags: #type
convertToRGBA bool convertToRGBA(LayoutConstraints layoutConstraints): Convert the image to a RGBA equivalent, using duplication and/or adding an opaque alpha channel. Tags: #type
copyPixelsTo void copyPixelsTo(Image img): Copy pixels to an image with same size and type. Both images should have plain pixels. Tags: #type #data #plain.
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: #type #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: #type
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.
errored bool errored(): Was there an error as a result of calling a public method of Image? It is now unusable. Tags: none.
flipHorizontally bool flipHorizontally(): Flip the image data horizontally. If the image has no data, the operation is successful. Tags: #type.
flipVertically bool flipVertically()
flipVerticallyLogical bool flipVerticallyLogical()
flipVerticallyPhysical bool flipVerticallyPhysical(): 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)
hasNonZeroSize bool hasNonZeroSize(): An image for which width > 0 and height > 0. Tags: none.
hasType 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.
height int height()
initWithNoData void initWithNoData(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.
isCompressed bool isCompressed(): A compressed image doesn't have its pixels available. Currently not supported. Tags: none.
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.
isPlainPixels bool isPlainPixels(): Undocumented in source. Be warned that the author may not have intended to support it.
isPlanar bool isPlanar(): A planar image is for example YUV420. If the image is planar, its lines are not accessible like that. Currently not supported. Tags: none.
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: #type #data
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 free.
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(ubyte)* scanline(int y): Returns a pointer to the y nth line of pixels. 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.
setSize void setSize(int width, int height, PixelType type, LayoutConstraints layoutConstraints): Clear the image and initialize a new image, with given dimensions and plain pixels. Tags: none.
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).
_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).

Meta

Source

See Implementation

gamut image functions

freeImageData

structs

Image