1/*
2 * Copyright 2015 Google Inc.
3 *
4 * Use of this source code is governed by a BSD-style license that can be
5 * found in the LICENSE file.
6 */
7
8#ifndef SkCodec_DEFINED
9#define SkCodec_DEFINED
10
11#include "include/codec/SkCodecAnimation.h"
12#include "include/codec/SkEncodedOrigin.h"
13#include "include/core/SkColor.h"
14#include "include/core/SkEncodedImageFormat.h"
15#include "include/core/SkImageInfo.h"
16#include "include/core/SkPixmap.h"
17#include "include/core/SkSize.h"
18#include "include/core/SkStream.h"
19#include "include/core/SkTypes.h"
20#include "include/core/SkYUVASizeInfo.h"
21#include "include/private/SkEncodedInfo.h"
22#include "include/private/SkNoncopyable.h"
23#include "include/private/SkTemplates.h"
24
25#include <vector>
26
27class SkColorSpace;
28class SkData;
29class SkFrameHolder;
30class SkPngChunkReader;
31class SkSampler;
32
33namespace DM {
34class CodecSrc;
35class ColorCodecSrc;
36}
37
38/**
39 * Abstraction layer directly on top of an image codec.
40 */
41class SK_API SkCodec : SkNoncopyable {
42public:
43 /**
44 * Minimum number of bytes that must be buffered in SkStream input.
45 *
46 * An SkStream passed to NewFromStream must be able to use this many
47 * bytes to determine the image type. Then the same SkStream must be
48 * passed to the correct decoder to read from the beginning.
49 *
50 * This can be accomplished by implementing peek() to support peeking
51 * this many bytes, or by implementing rewind() to be able to rewind()
52 * after reading this many bytes.
53 */
54 static constexpr size_t MinBufferedBytesNeeded() { return 32; }
55
56 /**
57 * Error codes for various SkCodec methods.
58 */
59 enum Result {
60 /**
61 * General return value for success.
62 */
63 kSuccess,
64 /**
65 * The input is incomplete. A partial image was generated.
66 */
67 kIncompleteInput,
68 /**
69 * Like kIncompleteInput, except the input had an error.
70 *
71 * If returned from an incremental decode, decoding cannot continue,
72 * even with more data.
73 */
74 kErrorInInput,
75 /**
76 * The generator cannot convert to match the request, ignoring
77 * dimensions.
78 */
79 kInvalidConversion,
80 /**
81 * The generator cannot scale to requested size.
82 */
83 kInvalidScale,
84 /**
85 * Parameters (besides info) are invalid. e.g. NULL pixels, rowBytes
86 * too small, etc.
87 */
88 kInvalidParameters,
89 /**
90 * The input did not contain a valid image.
91 */
92 kInvalidInput,
93 /**
94 * Fulfilling this request requires rewinding the input, which is not
95 * supported for this input.
96 */
97 kCouldNotRewind,
98 /**
99 * An internal error, such as OOM.
100 */
101 kInternalError,
102 /**
103 * This method is not implemented by this codec.
104 * FIXME: Perhaps this should be kUnsupported?
105 */
106 kUnimplemented,
107 };
108
109 /**
110 * Readable string representing the error code.
111 */
112 static const char* ResultToString(Result);
113
114 /**
115 * For container formats that contain both still images and image sequences,
116 * instruct the decoder how the output should be selected. (Refer to comments
117 * for each value for more details.)
118 */
119 enum class SelectionPolicy {
120 /**
121 * If the container format contains both still images and image sequences,
122 * SkCodec should choose one of the still images. This is the default.
123 */
124 kPreferStillImage,
125 /**
126 * If the container format contains both still images and image sequences,
127 * SkCodec should choose one of the image sequences for animation.
128 */
129 kPreferAnimation,
130 };
131
132 /**
133 * If this stream represents an encoded image that we know how to decode,
134 * return an SkCodec that can decode it. Otherwise return NULL.
135 *
136 * As stated above, this call must be able to peek or read
137 * MinBufferedBytesNeeded to determine the correct format, and then start
138 * reading from the beginning. First it will attempt to peek, and it
139 * assumes that if less than MinBufferedBytesNeeded bytes (but more than
140 * zero) are returned, this is because the stream is shorter than this,
141 * so falling back to reading would not provide more data. If peek()
142 * returns zero bytes, this call will instead attempt to read(). This
143 * will require that the stream can be rewind()ed.
144 *
145 * If Result is not NULL, it will be set to either kSuccess if an SkCodec
146 * is returned or a reason for the failure if NULL is returned.
147 *
148 * If SkPngChunkReader is not NULL, take a ref and pass it to libpng if
149 * the image is a png.
150 *
151 * If the SkPngChunkReader is not NULL then:
152 * If the image is not a PNG, the SkPngChunkReader will be ignored.
153 * If the image is a PNG, the SkPngChunkReader will be reffed.
154 * If the PNG has unknown chunks, the SkPngChunkReader will be used
155 * to handle these chunks. SkPngChunkReader will be called to read
156 * any unknown chunk at any point during the creation of the codec
157 * or the decode. Note that if SkPngChunkReader fails to read a
158 * chunk, this could result in a failure to create the codec or a
159 * failure to decode the image.
160 * If the PNG does not contain unknown chunks, the SkPngChunkReader
161 * will not be used or modified.
162 *
163 * If NULL is returned, the stream is deleted immediately. Otherwise, the
164 * SkCodec takes ownership of it, and will delete it when done with it.
165 */
166 static std::unique_ptr<SkCodec> MakeFromStream(
167 std::unique_ptr<SkStream>, Result* = nullptr,
168 SkPngChunkReader* = nullptr,
169 SelectionPolicy selectionPolicy = SelectionPolicy::kPreferStillImage);
170
171 /**
172 * If this data represents an encoded image that we know how to decode,
173 * return an SkCodec that can decode it. Otherwise return NULL.
174 *
175 * If the SkPngChunkReader is not NULL then:
176 * If the image is not a PNG, the SkPngChunkReader will be ignored.
177 * If the image is a PNG, the SkPngChunkReader will be reffed.
178 * If the PNG has unknown chunks, the SkPngChunkReader will be used
179 * to handle these chunks. SkPngChunkReader will be called to read
180 * any unknown chunk at any point during the creation of the codec
181 * or the decode. Note that if SkPngChunkReader fails to read a
182 * chunk, this could result in a failure to create the codec or a
183 * failure to decode the image.
184 * If the PNG does not contain unknown chunks, the SkPngChunkReader
185 * will not be used or modified.
186 */
187 static std::unique_ptr<SkCodec> MakeFromData(sk_sp<SkData>, SkPngChunkReader* = nullptr);
188
189 virtual ~SkCodec();
190
191 /**
192 * Return a reasonable SkImageInfo to decode into.
193 *
194 * If the image has an ICC profile that does not map to an SkColorSpace,
195 * the returned SkImageInfo will use SRGB.
196 */
197 SkImageInfo getInfo() const { return fEncodedInfo.makeImageInfo(); }
198
199 SkISize dimensions() const { return {fEncodedInfo.width(), fEncodedInfo.height()}; }
200 SkIRect bounds() const {
201 return SkIRect::MakeWH(fEncodedInfo.width(), fEncodedInfo.height());
202 }
203
204 /**
205 * Return the ICC profile of the encoded data.
206 */
207 const skcms_ICCProfile* getICCProfile() const {
208 return this->getEncodedInfo().profile();
209 }
210
211 /**
212 * Returns the image orientation stored in the EXIF data.
213 * If there is no EXIF data, or if we cannot read the EXIF data, returns kTopLeft.
214 */
215 SkEncodedOrigin getOrigin() const { return fOrigin; }
216
217 /**
218 * Return a size that approximately supports the desired scale factor.
219 * The codec may not be able to scale efficiently to the exact scale
220 * factor requested, so return a size that approximates that scale.
221 * The returned value is the codec's suggestion for the closest valid
222 * scale that it can natively support
223 */
224 SkISize getScaledDimensions(float desiredScale) const {
225 // Negative and zero scales are errors.
226 SkASSERT(desiredScale > 0.0f);
227 if (desiredScale <= 0.0f) {
228 return SkISize::Make(0, 0);
229 }
230
231 // Upscaling is not supported. Return the original size if the client
232 // requests an upscale.
233 if (desiredScale >= 1.0f) {
234 return this->dimensions();
235 }
236 return this->onGetScaledDimensions(desiredScale);
237 }
238
239 /**
240 * Return (via desiredSubset) a subset which can decoded from this codec,
241 * or false if this codec cannot decode subsets or anything similar to
242 * desiredSubset.
243 *
244 * @param desiredSubset In/out parameter. As input, a desired subset of
245 * the original bounds (as specified by getInfo). If true is returned,
246 * desiredSubset may have been modified to a subset which is
247 * supported. Although a particular change may have been made to
248 * desiredSubset to create something supported, it is possible other
249 * changes could result in a valid subset.
250 * If false is returned, desiredSubset's value is undefined.
251 * @return true if this codec supports decoding desiredSubset (as
252 * returned, potentially modified)
253 */
254 bool getValidSubset(SkIRect* desiredSubset) const {
255 return this->onGetValidSubset(desiredSubset);
256 }
257
258 /**
259 * Format of the encoded data.
260 */
261 SkEncodedImageFormat getEncodedFormat() const { return this->onGetEncodedFormat(); }
262
263 /**
264 * Whether or not the memory passed to getPixels is zero initialized.
265 */
266 enum ZeroInitialized {
267 /**
268 * The memory passed to getPixels is zero initialized. The SkCodec
269 * may take advantage of this by skipping writing zeroes.
270 */
271 kYes_ZeroInitialized,
272 /**
273 * The memory passed to getPixels has not been initialized to zero,
274 * so the SkCodec must write all zeroes to memory.
275 *
276 * This is the default. It will be used if no Options struct is used.
277 */
278 kNo_ZeroInitialized,
279 };
280
281 /**
282 * Additional options to pass to getPixels.
283 */
284 struct Options {
285 Options()
286 : fZeroInitialized(kNo_ZeroInitialized)
287 , fSubset(nullptr)
288 , fFrameIndex(0)
289 , fPriorFrame(kNoFrame)
290 {}
291
292 ZeroInitialized fZeroInitialized;
293 /**
294 * If not NULL, represents a subset of the original image to decode.
295 * Must be within the bounds returned by getInfo().
296 * If the EncodedFormat is SkEncodedImageFormat::kWEBP (the only one which
297 * currently supports subsets), the top and left values must be even.
298 *
299 * In getPixels and incremental decode, we will attempt to decode the
300 * exact rectangular subset specified by fSubset.
301 *
302 * In a scanline decode, it does not make sense to specify a subset
303 * top or subset height, since the client already controls which rows
304 * to get and which rows to skip. During scanline decodes, we will
305 * require that the subset top be zero and the subset height be equal
306 * to the full height. We will, however, use the values of
307 * subset left and subset width to decode partial scanlines on calls
308 * to getScanlines().
309 */
310 const SkIRect* fSubset;
311
312 /**
313 * The frame to decode.
314 *
315 * Only meaningful for multi-frame images.
316 */
317 int fFrameIndex;
318
319 /**
320 * If not kNoFrame, the dst already contains the prior frame at this index.
321 *
322 * Only meaningful for multi-frame images.
323 *
324 * If fFrameIndex needs to be blended with a prior frame (as reported by
325 * getFrameInfo[fFrameIndex].fRequiredFrame), the client can set this to
326 * any non-kRestorePrevious frame in [fRequiredFrame, fFrameIndex) to
327 * indicate that that frame is already in the dst. Options.fZeroInitialized
328 * is ignored in this case.
329 *
330 * If set to kNoFrame, the codec will decode any necessary required frame(s) first.
331 */
332 int fPriorFrame;
333 };
334
335 /**
336 * Decode into the given pixels, a block of memory of size at
337 * least (info.fHeight - 1) * rowBytes + (info.fWidth *
338 * bytesPerPixel)
339 *
340 * Repeated calls to this function should give the same results,
341 * allowing the PixelRef to be immutable.
342 *
343 * @param info A description of the format (config, size)
344 * expected by the caller. This can simply be identical
345 * to the info returned by getInfo().
346 *
347 * This contract also allows the caller to specify
348 * different output-configs, which the implementation can
349 * decide to support or not.
350 *
351 * A size that does not match getInfo() implies a request
352 * to scale. If the generator cannot perform this scale,
353 * it will return kInvalidScale.
354 *
355 * If the info contains a non-null SkColorSpace, the codec
356 * will perform the appropriate color space transformation.
357 *
358 * If the caller passes in the SkColorSpace that maps to the
359 * ICC profile reported by getICCProfile(), the color space
360 * transformation is a no-op.
361 *
362 * If the caller passes a null SkColorSpace, no color space
363 * transformation will be done.
364 *
365 * If a scanline decode is in progress, scanline mode will end, requiring the client to call
366 * startScanlineDecode() in order to return to decoding scanlines.
367 *
368 * @return Result kSuccess, or another value explaining the type of failure.
369 */
370 Result getPixels(const SkImageInfo& info, void* pixels, size_t rowBytes, const Options*);
371
372 /**
373 * Simplified version of getPixels() that uses the default Options.
374 */
375 Result getPixels(const SkImageInfo& info, void* pixels, size_t rowBytes) {
376 return this->getPixels(info, pixels, rowBytes, nullptr);
377 }
378
379 Result getPixels(const SkPixmap& pm, const Options* opts = nullptr) {
380 return this->getPixels(pm.info(), pm.writable_addr(), pm.rowBytes(), opts);
381 }
382
383 /**
384 * If decoding to YUV is supported, this returns true. Otherwise, this
385 * returns false and does not modify any of the parameters.
386 *
387 * @param sizeInfo Output parameter indicating the sizes and required
388 * allocation widths of the Y, U, V, and A planes. Given current codec
389 * limitations the size of the A plane will always be 0 and the Y, U, V
390 * channels will always be planar.
391 * @param colorSpace Output parameter. If non-NULL this is set to kJPEG,
392 * otherwise this is ignored.
393 */
394 bool queryYUV8(SkYUVASizeInfo* sizeInfo, SkYUVColorSpace* colorSpace) const {
395 if (nullptr == sizeInfo) {
396 return false;
397 }
398
399 bool result = this->onQueryYUV8(sizeInfo, colorSpace);
400 if (result) {
401 for (int i = 0; i <= 2; ++i) {
402 SkASSERT(sizeInfo->fSizes[i].fWidth > 0 && sizeInfo->fSizes[i].fHeight > 0 &&
403 sizeInfo->fWidthBytes[i] > 0);
404 }
405 SkASSERT(!sizeInfo->fSizes[3].fWidth &&
406 !sizeInfo->fSizes[3].fHeight &&
407 !sizeInfo->fWidthBytes[3]);
408 }
409 return result;
410 }
411
412 /**
413 * Returns kSuccess, or another value explaining the type of failure.
414 * This always attempts to perform a full decode. If the client only
415 * wants size, it should call queryYUV8().
416 *
417 * @param sizeInfo Needs to exactly match the values returned by the
418 * query, except the WidthBytes may be larger than the
419 * recommendation (but not smaller).
420 * @param planes Memory for each of the Y, U, and V planes.
421 */
422 Result getYUV8Planes(const SkYUVASizeInfo& sizeInfo, void* planes[SkYUVASizeInfo::kMaxCount]) {
423 if (!planes || !planes[0] || !planes[1] || !planes[2]) {
424 return kInvalidInput;
425 }
426 SkASSERT(!planes[3]); // TODO: is this a fair assumption?
427
428 if (!this->rewindIfNeeded()) {
429 return kCouldNotRewind;
430 }
431
432 return this->onGetYUV8Planes(sizeInfo, planes);
433 }
434
435 /**
436 * Prepare for an incremental decode with the specified options.
437 *
438 * This may require a rewind.
439 *
440 * If kIncompleteInput is returned, may be called again after more data has
441 * been provided to the source SkStream.
442 *
443 * @param dstInfo Info of the destination. If the dimensions do not match
444 * those of getInfo, this implies a scale.
445 * @param dst Memory to write to. Needs to be large enough to hold the subset,
446 * if present, or the full image as described in dstInfo.
447 * @param options Contains decoding options, including if memory is zero
448 * initialized and whether to decode a subset.
449 * @return Enum representing success or reason for failure.
450 */
451 Result startIncrementalDecode(const SkImageInfo& dstInfo, void* dst, size_t rowBytes,
452 const Options*);
453
454 Result startIncrementalDecode(const SkImageInfo& dstInfo, void* dst, size_t rowBytes) {
455 return this->startIncrementalDecode(dstInfo, dst, rowBytes, nullptr);
456 }
457
458 /**
459 * Start/continue the incremental decode.
460 *
461 * Not valid to call before a call to startIncrementalDecode() returns
462 * kSuccess.
463 *
464 * If kIncompleteInput is returned, may be called again after more data has
465 * been provided to the source SkStream.
466 *
467 * Unlike getPixels and getScanlines, this does not do any filling. This is
468 * left up to the caller, since they may be skipping lines or continuing the
469 * decode later. In the latter case, they may choose to initialize all lines
470 * first, or only initialize the remaining lines after the first call.
471 *
472 * @param rowsDecoded Optional output variable returning the total number of
473 * lines initialized. Only meaningful if this method returns kIncompleteInput.
474 * Otherwise the implementation may not set it.
475 * Note that some implementations may have initialized this many rows, but
476 * not necessarily finished those rows (e.g. interlaced PNG). This may be
477 * useful for determining what rows the client needs to initialize.
478 * @return kSuccess if all lines requested in startIncrementalDecode have
479 * been completely decoded. kIncompleteInput otherwise.
480 */
481 Result incrementalDecode(int* rowsDecoded = nullptr) {
482 if (!fStartedIncrementalDecode) {
483 return kInvalidParameters;
484 }
485 return this->onIncrementalDecode(rowsDecoded);
486 }
487
488 /**
489 * The remaining functions revolve around decoding scanlines.
490 */
491
492 /**
493 * Prepare for a scanline decode with the specified options.
494 *
495 * After this call, this class will be ready to decode the first scanline.
496 *
497 * This must be called in order to call getScanlines or skipScanlines.
498 *
499 * This may require rewinding the stream.
500 *
501 * Not all SkCodecs support this.
502 *
503 * @param dstInfo Info of the destination. If the dimensions do not match
504 * those of getInfo, this implies a scale.
505 * @param options Contains decoding options, including if memory is zero
506 * initialized.
507 * @return Enum representing success or reason for failure.
508 */
509 Result startScanlineDecode(const SkImageInfo& dstInfo, const Options* options);
510
511 /**
512 * Simplified version of startScanlineDecode() that uses the default Options.
513 */
514 Result startScanlineDecode(const SkImageInfo& dstInfo) {
515 return this->startScanlineDecode(dstInfo, nullptr);
516 }
517
518 /**
519 * Write the next countLines scanlines into dst.
520 *
521 * Not valid to call before calling startScanlineDecode().
522 *
523 * @param dst Must be non-null, and large enough to hold countLines
524 * scanlines of size rowBytes.
525 * @param countLines Number of lines to write.
526 * @param rowBytes Number of bytes per row. Must be large enough to hold
527 * a scanline based on the SkImageInfo used to create this object.
528 * @return the number of lines successfully decoded. If this value is
529 * less than countLines, this will fill the remaining lines with a
530 * default value.
531 */
532 int getScanlines(void* dst, int countLines, size_t rowBytes);
533
534 /**
535 * Skip count scanlines.
536 *
537 * Not valid to call before calling startScanlineDecode().
538 *
539 * The default version just calls onGetScanlines and discards the dst.
540 * NOTE: If skipped lines are the only lines with alpha, this default
541 * will make reallyHasAlpha return true, when it could have returned
542 * false.
543 *
544 * @return true if the scanlines were successfully skipped
545 * false on failure, possible reasons for failure include:
546 * An incomplete input image stream.
547 * Calling this function before calling startScanlineDecode().
548 * If countLines is less than zero or so large that it moves
549 * the current scanline past the end of the image.
550 */
551 bool skipScanlines(int countLines);
552
553 /**
554 * The order in which rows are output from the scanline decoder is not the
555 * same for all variations of all image types. This explains the possible
556 * output row orderings.
557 */
558 enum SkScanlineOrder {
559 /*
560 * By far the most common, this indicates that the image can be decoded
561 * reliably using the scanline decoder, and that rows will be output in
562 * the logical order.
563 */
564 kTopDown_SkScanlineOrder,
565
566 /*
567 * This indicates that the scanline decoder reliably outputs rows, but
568 * they will be returned in reverse order. If the scanline format is
569 * kBottomUp, the nextScanline() API can be used to determine the actual
570 * y-coordinate of the next output row, but the client is not forced
571 * to take advantage of this, given that it's not too tough to keep
572 * track independently.
573 *
574 * For full image decodes, it is safe to get all of the scanlines at
575 * once, since the decoder will handle inverting the rows as it
576 * decodes.
577 *
578 * For subset decodes and sampling, it is simplest to get and skip
579 * scanlines one at a time, using the nextScanline() API. It is
580 * possible to ask for larger chunks at a time, but this should be used
581 * with caution. As with full image decodes, the decoder will handle
582 * inverting the requested rows, but rows will still be delivered
583 * starting from the bottom of the image.
584 *
585 * Upside down bmps are an example.
586 */
587 kBottomUp_SkScanlineOrder,
588 };
589
590 /**
591 * An enum representing the order in which scanlines will be returned by
592 * the scanline decoder.
593 *
594 * This is undefined before startScanlineDecode() is called.
595 */
596 SkScanlineOrder getScanlineOrder() const { return this->onGetScanlineOrder(); }
597
598 /**
599 * Returns the y-coordinate of the next row to be returned by the scanline
600 * decoder.
601 *
602 * This will equal fCurrScanline, except in the case of strangely
603 * encoded image types (bottom-up bmps).
604 *
605 * Results are undefined when not in scanline decoding mode.
606 */
607 int nextScanline() const { return this->outputScanline(fCurrScanline); }
608
609 /**
610 * Returns the output y-coordinate of the row that corresponds to an input
611 * y-coordinate. The input y-coordinate represents where the scanline
612 * is located in the encoded data.
613 *
614 * This will equal inputScanline, except in the case of strangely
615 * encoded image types (bottom-up bmps, interlaced gifs).
616 */
617 int outputScanline(int inputScanline) const;
618
619 /**
620 * Return the number of frames in the image.
621 *
622 * May require reading through the stream.
623 */
624 int getFrameCount() {
625 return this->onGetFrameCount();
626 }
627
628 // Sentinel value used when a frame index implies "no frame":
629 // - FrameInfo::fRequiredFrame set to this value means the frame
630 // is independent.
631 // - Options::fPriorFrame set to this value means no (relevant) prior frame
632 // is residing in dst's memory.
633 static constexpr int kNoFrame = -1;
634
635 // This transitional definition was added in August 2018, and will eventually be removed.
636#ifdef SK_LEGACY_SKCODEC_NONE_ENUM
637 static constexpr int kNone = kNoFrame;
638#endif
639
640 /**
641 * Information about individual frames in a multi-framed image.
642 */
643 struct FrameInfo {
644 /**
645 * The frame that this frame needs to be blended with, or
646 * kNoFrame if this frame is independent (so it can be
647 * drawn over an uninitialized buffer).
648 *
649 * Note that this is the *earliest* frame that can be used
650 * for blending. Any frame from [fRequiredFrame, i) can be
651 * used, unless its fDisposalMethod is kRestorePrevious.
652 */
653 int fRequiredFrame;
654
655 /**
656 * Number of milliseconds to show this frame.
657 */
658 int fDuration;
659
660 /**
661 * Whether the end marker for this frame is contained in the stream.
662 *
663 * Note: this does not guarantee that an attempt to decode will be complete.
664 * There could be an error in the stream.
665 */
666 bool fFullyReceived;
667
668 /**
669 * This is conservative; it will still return non-opaque if e.g. a
670 * color index-based frame has a color with alpha but does not use it.
671 */
672 SkAlphaType fAlphaType;
673
674 /**
675 * How this frame should be modified before decoding the next one.
676 */
677 SkCodecAnimation::DisposalMethod fDisposalMethod;
678 };
679
680 /**
681 * Return info about a single frame.
682 *
683 * Only supported by multi-frame images. Does not read through the stream,
684 * so it should be called after getFrameCount() to parse any frames that
685 * have not already been parsed.
686 */
687 bool getFrameInfo(int index, FrameInfo* info) const {
688 if (index < 0) {
689 return false;
690 }
691 return this->onGetFrameInfo(index, info);
692 }
693
694 /**
695 * Return info about all the frames in the image.
696 *
697 * May require reading through the stream to determine info about the
698 * frames (including the count).
699 *
700 * As such, future decoding calls may require a rewind.
701 *
702 * For still (non-animated) image codecs, this will return an empty vector.
703 */
704 std::vector<FrameInfo> getFrameInfo();
705
706 static constexpr int kRepetitionCountInfinite = -1;
707
708 /**
709 * Return the number of times to repeat, if this image is animated. This number does not
710 * include the first play through of each frame. For example, a repetition count of 4 means
711 * that each frame is played 5 times and then the animation stops.
712 *
713 * It can return kRepetitionCountInfinite, a negative number, meaning that the animation
714 * should loop forever.
715 *
716 * May require reading the stream to find the repetition count.
717 *
718 * As such, future decoding calls may require a rewind.
719 *
720 * For still (non-animated) image codecs, this will return 0.
721 */
722 int getRepetitionCount() {
723 return this->onGetRepetitionCount();
724 }
725
726 // Register a decoder at runtime by passing two function pointers:
727 // - peek() to return true if the span of bytes appears to be your encoded format;
728 // - make() to attempt to create an SkCodec from the given stream.
729 // Not thread safe.
730 static void Register(
731 bool (*peek)(const void*, size_t),
732 std::unique_ptr<SkCodec> (*make)(std::unique_ptr<SkStream>, SkCodec::Result*));
733
734protected:
735 const SkEncodedInfo& getEncodedInfo() const { return fEncodedInfo; }
736
737 using XformFormat = skcms_PixelFormat;
738
739 SkCodec(SkEncodedInfo&&,
740 XformFormat srcFormat,
741 std::unique_ptr<SkStream>,
742 SkEncodedOrigin = kTopLeft_SkEncodedOrigin);
743
744 virtual SkISize onGetScaledDimensions(float /*desiredScale*/) const {
745 // By default, scaling is not supported.
746 return this->dimensions();
747 }
748
749 // FIXME: What to do about subsets??
750 /**
751 * Subclasses should override if they support dimensions other than the
752 * srcInfo's.
753 */
754 virtual bool onDimensionsSupported(const SkISize&) {
755 return false;
756 }
757
758 virtual SkEncodedImageFormat onGetEncodedFormat() const = 0;
759
760 /**
761 * @param rowsDecoded When the encoded image stream is incomplete, this function
762 * will return kIncompleteInput and rowsDecoded will be set to
763 * the number of scanlines that were successfully decoded.
764 * This will allow getPixels() to fill the uninitialized memory.
765 */
766 virtual Result onGetPixels(const SkImageInfo& info,
767 void* pixels, size_t rowBytes, const Options&,
768 int* rowsDecoded) = 0;
769
770 virtual bool onQueryYUV8(SkYUVASizeInfo*, SkYUVColorSpace*) const {
771 return false;
772 }
773
774 virtual Result onGetYUV8Planes(const SkYUVASizeInfo&,
775 void*[SkYUVASizeInfo::kMaxCount] /*planes*/) {
776 return kUnimplemented;
777 }
778
779 virtual bool onGetValidSubset(SkIRect* /*desiredSubset*/) const {
780 // By default, subsets are not supported.
781 return false;
782 }
783
784 /**
785 * If the stream was previously read, attempt to rewind.
786 *
787 * If the stream needed to be rewound, call onRewind.
788 * @returns true if the codec is at the right position and can be used.
789 * false if there was a failure to rewind.
790 *
791 * This is called by getPixels(), getYUV8Planes(), startIncrementalDecode() and
792 * startScanlineDecode(). Subclasses may call if they need to rewind at another time.
793 */
794 bool SK_WARN_UNUSED_RESULT rewindIfNeeded();
795
796 /**
797 * Called by rewindIfNeeded, if the stream needed to be rewound.
798 *
799 * Subclasses should do any set up needed after a rewind.
800 */
801 virtual bool onRewind() {
802 return true;
803 }
804
805 /**
806 * Get method for the input stream
807 */
808 SkStream* stream() {
809 return fStream.get();
810 }
811
812 /**
813 * The remaining functions revolve around decoding scanlines.
814 */
815
816 /**
817 * Most images types will be kTopDown and will not need to override this function.
818 */
819 virtual SkScanlineOrder onGetScanlineOrder() const { return kTopDown_SkScanlineOrder; }
820
821 const SkImageInfo& dstInfo() const { return fDstInfo; }
822
823 const Options& options() const { return fOptions; }
824
825 /**
826 * Returns the number of scanlines that have been decoded so far.
827 * This is unaffected by the SkScanlineOrder.
828 *
829 * Returns -1 if we have not started a scanline decode.
830 */
831 int currScanline() const { return fCurrScanline; }
832
833 virtual int onOutputScanline(int inputScanline) const;
834
835 /**
836 * Return whether we can convert to dst.
837 *
838 * Will be called for the appropriate frame, prior to initializing the colorXform.
839 */
840 virtual bool conversionSupported(const SkImageInfo& dst, bool srcIsOpaque,
841 bool needsColorXform);
842
843 // Some classes never need a colorXform e.g.
844 // - ICO uses its embedded codec's colorXform
845 // - WBMP is just Black/White
846 virtual bool usesColorXform() const { return true; }
847 void applyColorXform(void* dst, const void* src, int count) const;
848
849 bool colorXform() const { return fXformTime != kNo_XformTime; }
850 bool xformOnDecode() const { return fXformTime == kDecodeRow_XformTime; }
851
852 virtual int onGetFrameCount() {
853 return 1;
854 }
855
856 virtual bool onGetFrameInfo(int, FrameInfo*) const {
857 return false;
858 }
859
860 virtual int onGetRepetitionCount() {
861 return 0;
862 }
863
864private:
865 const SkEncodedInfo fEncodedInfo;
866 const XformFormat fSrcXformFormat;
867 std::unique_ptr<SkStream> fStream;
868 bool fNeedsRewind;
869 const SkEncodedOrigin fOrigin;
870
871 SkImageInfo fDstInfo;
872 Options fOptions;
873
874 enum XformTime {
875 kNo_XformTime,
876 kPalette_XformTime,
877 kDecodeRow_XformTime,
878 };
879 XformTime fXformTime;
880 XformFormat fDstXformFormat; // Based on fDstInfo.
881 skcms_ICCProfile fDstProfile;
882 skcms_AlphaFormat fDstXformAlphaFormat;
883
884 // Only meaningful during scanline decodes.
885 int fCurrScanline;
886
887 bool fStartedIncrementalDecode;
888
889 bool initializeColorXform(const SkImageInfo& dstInfo, SkEncodedInfo::Alpha, bool srcIsOpaque);
890
891 /**
892 * Return whether these dimensions are supported as a scale.
893 *
894 * The codec may choose to cache the information about scale and subset.
895 * Either way, the same information will be passed to onGetPixels/onStart
896 * on success.
897 *
898 * This must return true for a size returned from getScaledDimensions.
899 */
900 bool dimensionsSupported(const SkISize& dim) {
901 return dim == this->dimensions() || this->onDimensionsSupported(dim);
902 }
903
904 /**
905 * For multi-framed images, return the object with information about the frames.
906 */
907 virtual const SkFrameHolder* getFrameHolder() const {
908 return nullptr;
909 }
910
911 /**
912 * Check for a valid Options.fFrameIndex, and decode prior frames if necessary.
913 */
914 Result handleFrameIndex(const SkImageInfo&, void* pixels, size_t rowBytes, const Options&);
915
916 // Methods for scanline decoding.
917 virtual Result onStartScanlineDecode(const SkImageInfo& /*dstInfo*/,
918 const Options& /*options*/) {
919 return kUnimplemented;
920 }
921
922 virtual Result onStartIncrementalDecode(const SkImageInfo& /*dstInfo*/, void*, size_t,
923 const Options&) {
924 return kUnimplemented;
925 }
926
927 virtual Result onIncrementalDecode(int*) {
928 return kUnimplemented;
929 }
930
931
932 virtual bool onSkipScanlines(int /*countLines*/) { return false; }
933
934 virtual int onGetScanlines(void* /*dst*/, int /*countLines*/, size_t /*rowBytes*/) { return 0; }
935
936 /**
937 * On an incomplete decode, getPixels() and getScanlines() will call this function
938 * to fill any uinitialized memory.
939 *
940 * @param dstInfo Contains the destination color type
941 * Contains the destination alpha type
942 * Contains the destination width
943 * The height stored in this info is unused
944 * @param dst Pointer to the start of destination pixel memory
945 * @param rowBytes Stride length in destination pixel memory
946 * @param zeroInit Indicates if memory is zero initialized
947 * @param linesRequested Number of lines that the client requested
948 * @param linesDecoded Number of lines that were successfully decoded
949 */
950 void fillIncompleteImage(const SkImageInfo& dstInfo, void* dst, size_t rowBytes,
951 ZeroInitialized zeroInit, int linesRequested, int linesDecoded);
952
953 /**
954 * Return an object which will allow forcing scanline decodes to sample in X.
955 *
956 * May create a sampler, if one is not currently being used. Otherwise, does
957 * not affect ownership.
958 *
959 * Only valid during scanline decoding or incremental decoding.
960 */
961 virtual SkSampler* getSampler(bool /*createIfNecessary*/) { return nullptr; }
962
963 friend class DM::CodecSrc; // for fillIncompleteImage
964 friend class SkSampledCodec;
965 friend class SkIcoCodec;
966 friend class SkAndroidCodec; // for fEncodedInfo
967};
968#endif // SkCodec_DEFINED
969