Line data    Source code

       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 <cstdint> // for uint8_t
      10             : #include "mozilla/Attributes.h"
      11             : #include "mozilla/Likely.h"
      12             : 
      13             : namespace mozilla {
      14             : namespace image {
      15             : 
      16             : /**
      17             :  * An enumeration representing the result of a drawing operation.
      18             :  *
      19             :  * Most users of DrawResult will only be interested in whether the value is
      20             :  * SUCCESS or not. The other values are primarily useful for debugging and error
      21             :  * handling.
      22             :  *
      23             :  * SUCCESS: We successfully drew a completely decoded frame of the requested
      24             :  * size. Drawing again with FLAG_SYNC_DECODE would not change the result.
      25             :  *
      26             :  * INCOMPLETE: We successfully drew a frame that was partially decoded. (Note
      27             :  * that successfully drawing a partially decoded frame may not actually draw any
      28             :  * pixels!) Drawing again with FLAG_SYNC_DECODE would improve the result.
      29             :  *
      30             :  * WRONG_SIZE: We successfully drew a wrongly-sized frame that had to be scaled.
      31             :  * This is only returned if drawing again with FLAG_SYNC_DECODE would improve
      32             :  * the result; if the size requested was larger than the intrinsic size of the
      33             :  * image, for example, we would generally have to scale whether FLAG_SYNC_DECODE
      34             :  * was specified or not, and therefore we would not return WRONG_SIZE.
      35             :  *
      36             :  * NOT_READY: We failed to draw because no decoded version of the image was
      37             :  * available. Drawing again with FLAG_SYNC_DECODE would improve the result.
      38             :  * (Though FLAG_SYNC_DECODE will not necessarily work until after the image's
      39             :  * load event!)
      40             :  *
      41             :  * TEMPORARY_ERROR: We failed to draw due to a temporary error. Drawing may
      42             :  * succeed at a later time.
      43             :  *
      44             :  * BAD_IMAGE: We failed to draw because the image has an error. This is a
      45             :  * permanent condition.
      46             :  *
      47             :  * BAD_ARGS: We failed to draw because bad arguments were passed to draw().
      48             :  */
      49             : enum class MOZ_MUST_USE_TYPE DrawResult : uint8_t
      50             : {
      51             :   SUCCESS,
      52             :   INCOMPLETE,
      53             :   WRONG_SIZE,
      54             :   NOT_READY,
      55             :   TEMPORARY_ERROR,
      56             :   BAD_IMAGE,
      57             :   BAD_ARGS
      58             : };
      59             : 
      60             : /**
      61             :  * You can combine DrawResults with &. By analogy to bitwise-&, the result is
      62             :  * DrawResult::SUCCESS only if both operands are DrawResult::SUCCESS. Otherwise,
      63             :  * a failing DrawResult is returned; we favor the left operand's failure when
      64             :  * deciding which failure to return, with the exception that we always prefer
      65             :  * any other kind of failure over DrawResult::BAD_IMAGE, since other failures
      66             :  * are recoverable and we want to know if any recoverable failures occurred.
      67             :  */
      68             : inline DrawResult
      69         145 : operator&(const DrawResult aLeft, const DrawResult aRight)
      70             : {
      71         145 :   if (MOZ_LIKELY(aLeft == DrawResult::SUCCESS)) {
      72         145 :     return aRight;
      73             :   }
      74           0 :   if (aLeft == DrawResult::BAD_IMAGE && aRight != DrawResult::SUCCESS) {
      75           0 :     return aRight;
      76             :   }
      77           0 :   return aLeft;
      78             : }
      79             : 
      80             : inline DrawResult&
      81         145 : operator&=(DrawResult& aLeft, const DrawResult aRight)
      82             : {
      83         145 :   aLeft = aLeft & aRight;
      84         145 :   return aLeft;
      85             : }
      86             : 
      87             : /**
      88             :  * A struct used during painting to provide input flags to determine how
      89             :  * imagelib draw calls should behave and an output DrawResult to return
      90             :  * information about the result of any imagelib draw calls that may have
      91             :  * occurred.
      92             :  */
      93             : struct imgDrawingParams {
      94          39 :   explicit imgDrawingParams(uint32_t aImageFlags = 0)
      95          39 :     : imageFlags(aImageFlags), result(DrawResult::SUCCESS)
      96          39 :   {}
      97             : 
      98             :   const uint32_t imageFlags; // imgIContainer::FLAG_* image flags to pass to
      99             :                              // image lib draw calls.
     100             :   DrawResult result;         // To return results from image lib painting.
     101             : };
     102             : 
     103             : } // namespace image
     104             : } // namespace mozilla
     105             : 
     106             : #endif // mozilla_image_DrawResult_h