image/DrawResult.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef mozilla_image_DrawResult_h
   7 #define mozilla_image_DrawResult_h
   8
   9 #include "mozilla/Attributes.h"
  10 #include "mozilla/Likely.h"
  11
  12 namespace mozilla {
  13 namespace image {
  14
  15 /**
  16  * An enumeration representing the result of a drawing operation.
  17  *
  18  * Most users of DrawResult will only be interested in whether the value is
  19  * SUCCESS or not. The other values are primarily useful for debugging and error
  20  * handling.
  21  *
  22  * SUCCESS: We successfully drew a completely decoded frame of the requested
  23  * size. Drawing again with FLAG_SYNC_DECODE would not change the result.
  24  *
  25  * INCOMPLETE: We successfully drew a frame that was partially decoded. (Note
  26  * that successfully drawing a partially decoded frame may not actually draw any
  27  * pixels!) Drawing again with FLAG_SYNC_DECODE would improve the result.
  28  *
  29  * WRONG_SIZE: We successfully drew a wrongly-sized frame that had to be scaled.
  30  * This is only returned if drawing again with FLAG_SYNC_DECODE would improve
  31  * the result; if the size requested was larger than the intrinsic size of the
  32  * image, for example, we would generally have to scale whether FLAG_SYNC_DECODE
  33  * was specified or not, and therefore we would not return WRONG_SIZE.
  34  *
  35  * NOT_READY: We failed to draw because no decoded version of the image was
  36  * available. Drawing again with FLAG_SYNC_DECODE would improve the result.
  37  * (Though FLAG_SYNC_DECODE will not necessarily work until after the image's
  38  * load event!)
  39  *
  40  * TEMPORARY_ERROR: We failed to draw due to a temporary error. Drawing may
  41  * succeed at a later time.
  42  *
  43  * BAD_IMAGE: We failed to draw because the image has an error. This is a
  44  * permanent condition.
  45  *
  46  * BAD_ARGS: We failed to draw because bad arguments were passed to draw().
  47  */
  48 enum class DrawResult : uint8_t
  49 {
  50   SUCCESS,
  51   INCOMPLETE,
  52   WRONG_SIZE,
  53   NOT_READY,
  54   TEMPORARY_ERROR,
  55   BAD_IMAGE,
  56   BAD_ARGS
  57 };
  58
  59 /**
  60  * You can combine DrawResults with &. By analogy to bitwise-&, the result is
  61  * DrawResult::SUCCESS only if both operands are DrawResult::SUCCESS. Otherwise,
  62  * a failing DrawResult is returned; we favor the left operand's failure when
  63  * deciding which failure to return, with the exception that we always prefer
  64  * any other kind of failure over DrawResult::BAD_IMAGE, since other failures
  65  * are recoverable and we want to know if any recoverable failures occurred.
  66  */
  67 inline DrawResult
  68 operator&(const DrawResult aLeft, const DrawResult aRight)
  69 {
  70   if (MOZ_LIKELY(aLeft == DrawResult::SUCCESS)) {
  71     return aRight;
  72   }
  73   if (aLeft == DrawResult::BAD_IMAGE && aRight != DrawResult::SUCCESS) {
  74     return aRight;
  75   }
  76   return aLeft;
  77 }
  78
  79 inline DrawResult&
  80 operator&=(DrawResult& aLeft, const DrawResult aRight)
  81 {
  82   aLeft = aLeft & aRight;
  83   return aLeft;
  84 }
  85
  86 } // namespace image
  87 } // namespace mozilla
  88
  89 #endif // mozilla_image_DrawResult_h