Codec

class Codec

Codec Abstraction layer directly on top of an image codec.

Classes

DisposalMethod

This specifies how the next frame is based on this frame.

FrameInfo

Information about individual frames in a multi-framed image.

Options

Additional options to pass to getPixels.

Result

Error codes for various Codec methods.

ScanlineOrder

The order in which rows are output from the scanline decoder is not the

SelectionPolicy

For container formats that contain both still images and image sequences,

ZeroInitialized

Whether or not the memory passed to getPixels is zero initialized.

Methods

MakeFromData

If this data represents an encoded image that we know how to decode, return an Codec that can decode it.

MinBufferedBytesNeeded

ResultToString

Returns a textual representation of Codec.Result

__init__

If this stream represents an encoded image that we know how to decode, return an Codec that can decode it.

bounds

dimensions

getEncodedFormat

Format of the encoded data.

getFrameCount

Return the number of frames in the image.

getFrameInfo

Overloaded function.

getInfo

Return a reasonable ImageInfo to decode into.

getOrigin

Returns the image orientation stored in the EXIF data.

getPixels

Overloaded function.

getRepetitionCount

Return the number of times to repeat, if this image is animated.

getScaledDimensions

Return a size that approximately supports the desired scale factor.

getScanlineOrder

An enum representing the order in which scanlines will be returned by the scanline decoder.

getScanlines

Write the next countLines scanlines into dst.

getValidSubset

Return (via desiredSubset) a subset which can decoded from this codec, or false if this codec cannot decode subsets or anything similar to desiredSubset.

getYUVAPlanes

Returns kSuccess, or another value explaining the type of failure.

incrementalDecode

Start/continue the incremental decode.

nextScanline

Returns the y-coordinate of the next row to be returned by the scanline decoder.

outputScanline

Returns the output y-coordinate of the row that corresponds to an input y-coordinate.

queryYUVAInfo

If decoding to YUV is supported, this returns true.

skipScanlines

Skip count scanlines.

startIncrementalDecode

Prepare for an incremental decode with the specified options.

startScanlineDecode

Prepare for a scanline decode with the specified options.

Attributes

kCouldNotRewind

kErrorInInput

kIncompleteInput

kInternalError

kInvalidConversion

kInvalidInput

kInvalidParameters

kInvalidScale

kKeep

kNoFrame

kNo_ZeroInitialized

kPreferAnimation

kPreferStillImage

kRepetitionCountInfinite

kRestoreBGColor

kRestorePrevious

kSuccess

kUnimplemented

kYes_ZeroInitialized

Methods

static Codec.MakeFromData(data: buffer) skia.Codec

If this data represents an encoded image that we know how to decode, return an Codec that can decode it. Otherwise return NULL.

static Codec.MinBufferedBytesNeeded() int
static Codec.ResultToString(result: skia.Codec.Result) str

Returns a textual representation of Codec.Result

Codec.__init__(self: skia.Codec, data: buffer) None

If this stream represents an encoded image that we know how to decode, return an Codec that can decode it. Otherwise return None.

Codec.bounds(self: skia.Codec) skia.IRect
Codec.dimensions(self: skia.Codec) skia.ISize
Codec.getEncodedFormat(self: skia.Codec) SkEncodedImageFormat

Format of the encoded data.

Codec.getFrameCount(self: skia.Codec) int

Return the number of frames in the image.

May require reading through the stream.

Codec.getFrameInfo(*args, **kwargs)

Overloaded function.

  1. getFrameInfo(self: skia.Codec, index: int, info: skia.Codec.FrameInfo) -> bool

    Return info about a single frame.

    Only supported by multi-frame images. Does not read through the stream, so it should be called after getFrameCount() to parse any frames that have not already been parsed.

  2. getFrameInfo(self: skia.Codec) -> List[skia.Codec.FrameInfo]

    Return info about all the frames in the image.

    May require reading through the stream to determine info about the frames (including the count).

    As such, future decoding calls may require a rewind.

    For still (non-animated) image codecs, this will return an empty vector.

Codec.getInfo(self: skia.Codec) SkImageInfo

Return a reasonable ImageInfo to decode into.

If the image has an ICC profile that does not map to an ColorSpace, the returned ImageInfo will use SRGB.

Codec.getOrigin(self: skia.Codec) skia.EncodedOrigin

Returns the image orientation stored in the EXIF data. If there is no EXIF data, or if we cannot read the EXIF data, returns kTopLeft.

Codec.getPixels(*args, **kwargs)

Overloaded function.

  1. getPixels(self: skia.Codec, info: SkImageInfo, data: buffer, rowBytes: int, options: skia.Codec.Options = None) -> skia.Codec.Result

    Decode into the given pixels, a block of memory of size at least (info.fHeight - 1) * rowBytes + (info.fWidth * bytesPerPixel)

    Repeated calls to this function should give the same results, allowing the PixelRef to be immutable.

    If a scanline decode is in progress, scanline mode will end, requiring the client to call startScanlineDecode() in order to return to decoding scanlines.

    info:

    A description of the format (config, size) expected by the caller. This can simply be identical to the info returned by getInfo().

    This contract also allows the caller to specify different output-configs, which the implementation can decide to support or not.

    A size that does not match getInfo() implies a request to scale. If the generator cannot perform this scale, it will return kInvalidScale.

    If the info contains a non-null SkColorSpace, the codec will perform the appropriate color space transformation.

    If the caller passes in the SkColorSpace that maps to the ICC profile reported by getICCProfile(), the color space transformation is a no-op.

    If the caller passes a null SkColorSpace, no color space transformation will be done.

    return:

    Result kSuccess, or another value explaining the type of failure.

  2. getPixels(self: skia.Codec, pixmap: SkPixmap, options: skia.Codec.Options = None) -> skia.Codec.Result

Codec.getRepetitionCount(self: skia.Codec) int

Return the number of times to repeat, if this image is animated. This number does not include the first play through of each frame. For example, a repetition count of 4 means that each frame is played 5 times and then the animation stops.

It can return kRepetitionCountInfinite, a negative number, meaning that the animation should loop forever.

May require reading the stream to find the repetition count.

As such, future decoding calls may require a rewind.

For still (non-animated) image codecs, this will return 0.

Codec.getScaledDimensions(self: skia.Codec, desiredScale: float) skia.ISize

Return a size that approximately supports the desired scale factor. The codec may not be able to scale efficiently to the exact scale factor requested, so return a size that approximates that scale. The returned value is the codec’s suggestion for the closest valid scale that it can natively support

Codec.getScanlineOrder(self: skia.Codec) skia.Codec.ScanlineOrder

An enum representing the order in which scanlines will be returned by the scanline decoder.

This is undefined before startScanlineDecode() is called.

Codec.getScanlines(self: skia.Codec, dst: buffer, countLines: int, rowBytes: int) int

Write the next countLines scanlines into dst.

Not valid to call before calling startScanlineDecode().

Parameters:
  • dst – Must be non-null, and large enough to hold countLines scanlines of size rowBytes.

  • countLines – Number of lines to write.

  • rowBytes – Number of bytes per row. Must be large enough to hold a scanline based on the ImageInfo used to create this object.

Returns:

the number of lines successfully decoded. If this value is less than countLines, this will fill the remaining lines with a default value.

Codec.getValidSubset(self: skia.Codec, desiredSubset: skia.IRect) bool

Return (via desiredSubset) a subset which can decoded from this codec, or false if this codec cannot decode subsets or anything similar to desiredSubset.

Parameters:

desiredSubset – In/out parameter. As input, a desired subset of the original bounds (as specified by getInfo). If true is returned, desiredSubset may have been modified to a subset which is supported. Although a particular change may have been made to desiredSubset to create something supported, it is possible other changes could result in a valid subset. If false is returned, desiredSubset’s value is undefined.

Returns:

true if this codec supports decoding desiredSubset (as returned, potentially modified)

Codec.getYUVAPlanes(self: skia.Codec, yuvaPixmaps: SkYUVAPixmaps) skia.Codec.Result

Returns kSuccess, or another value explaining the type of failure. This always attempts to perform a full decode. To get the planar configuration without decoding use queryYUVAInfo().

Parameters:

yuvaPixmaps – Contains preallocated pixmaps configured according to a successful call to queryYUVAInfo().

Codec.incrementalDecode(self: skia.Codec, rowsDecoded: int = None) skia.Codec.Result

Start/continue the incremental decode.

Not valid to call before a call to startIncrementalDecode() returns kSuccess.

If kIncompleteInput is returned, may be called again after more data has been provided to the source SkStream.

Unlike getPixels and getScanlines, this does not do any filling. This is left up to the caller, since they may be skipping lines or continuing the decode later. In the latter case, they may choose to initialize all lines first, or only initialize the remaining lines after the first call.

Parameters:

rowsDecoded – Optional output variable returning the total number of lines initialized. Only meaningful if this method returns kIncompleteInput. Otherwise the implementation may not set it. Note that some implementations may have initialized this many rows, but not necessarily finished those rows (e.g. interlaced PNG). This may be useful for determining what rows the client needs to initialize.

Returns:

kSuccess if all lines requested in startIncrementalDecode have been completely decoded. kIncompleteInput otherwise.

Codec.nextScanline(self: skia.Codec) int

Returns the y-coordinate of the next row to be returned by the scanline decoder.

This will equal fCurrScanline, except in the case of strangely encoded image types (bottom-up bmps).

Results are undefined when not in scanline decoding mode.

Codec.outputScanline(self: skia.Codec, inputScanline: int) int

Returns the output y-coordinate of the row that corresponds to an input y-coordinate. The input y-coordinate represents where the scanline is located in the encoded data.

This will equal inputScanline, except in the case of strangely encoded image types (bottom-up bmps, interlaced gifs).

Codec.queryYUVAInfo(self: skia.Codec, supportedDataTypes: SkYUVAPixmapInfo::SupportedDataTypes) object

If decoding to YUV is supported, this returns true. Otherwise, this returns false;

Parameters:

supportedDataTypes – Indicates the data type/planar config combinations that are supported by the caller. If the generator supports decoding to YUV(A), but not as a type in supportedDataTypes, this method returns false.

Returns:

Output that specifies the planar configuration, subsampling, orientation, chroma siting, plane color types, and row bytes.

Codec.skipScanlines(self: skia.Codec, countLines: int) bool

Skip count scanlines.

Not valid to call before calling startScanlineDecode().

The default version just calls onGetScanlines and discards the dst. NOTE: If skipped lines are the only lines with alpha, this default will make reallyHasAlpha return true, when it could have returned false.

Returns:

true if the scanlines were successfully skipped false on failure, possible reasons for failure include:

  • An incomplete input image stream.

  • Calling this function before calling startScanlineDecode().

  • If countLines is less than zero or so large that it moves

    the current scanline past the end of the image.

Codec.startIncrementalDecode(self: skia.Codec, dstInfo: SkImageInfo, dst: buffer, rowBytes: int, options: skia.Codec.Options = None) skia.Codec.Result

Prepare for an incremental decode with the specified options.

This may require a rewind.

If kIncompleteInput is returned, may be called again after more data has been provided to the source Stream.

Parameters:
  • dstInfo – Info of the destination. If the dimensions do not match those of getInfo, this implies a scale.

  • dst – Memory to write to. Needs to be large enough to hold the subset, if present, or the full image as described in dstInfo.

  • options – Contains decoding options, including if memory is zero initialized and whether to decode a subset.

Returns:

Enum representing success or reason for failure.

Codec.startScanlineDecode(self: skia.Codec, dstInfo: SkImageInfo, options: skia.Codec.Options = None) skia.Codec.Result

Prepare for a scanline decode with the specified options.

After this call, this class will be ready to decode the first scanline.

This must be called in order to call getScanlines() or skipScanlines().

This may require rewinding the stream.

Not all Codecs support this.

Parameters:
  • dstInfo – Info of the destination. If the dimensions do not match those of getInfo, this implies a scale.

  • options – Contains decoding options, including if memory is zero initialized.

Returns:

Enum representing success or reason for failure.

Attributes

Codec.kCouldNotRewind = <Result.kCouldNotRewind: 7>
Codec.kErrorInInput = <Result.kErrorInInput: 2>
Codec.kIncompleteInput = <Result.kIncompleteInput: 1>
Codec.kInternalError = <Result.kInternalError: 8>
Codec.kInvalidConversion = <Result.kInvalidConversion: 3>
Codec.kInvalidInput = <Result.kInvalidInput: 6>
Codec.kInvalidParameters = <Result.kInvalidParameters: 5>
Codec.kInvalidScale = <Result.kInvalidScale: 4>
Codec.kKeep = <DisposalMethod.kKeep: 1>
Codec.kNoFrame = -1
Codec.kNo_ZeroInitialized = <ZeroInitialized.kNo_ZeroInitialized: 1>
Codec.kPreferAnimation = <SelectionPolicy.kPreferAnimation: 1>
Codec.kPreferStillImage = <SelectionPolicy.kPreferStillImage: 0>
Codec.kRepetitionCountInfinite = -1
Codec.kRestoreBGColor = <DisposalMethod.kRestoreBGColor: 2>
Codec.kRestorePrevious = <DisposalMethod.kRestorePrevious: 3>
Codec.kSuccess = <Result.kSuccess: 0>
Codec.kUnimplemented = <Result.kUnimplemented: 9>
Codec.kYes_ZeroInitialized = <ZeroInitialized.kYes_ZeroInitialized: 0>