tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

ImgDrawResult.h (4594B)

      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_ImgDrawResult_h
      7 #define mozilla_image_ImgDrawResult_h
      8 
      9 #include <cstdint>  // for uint8_t
     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 ImgDrawResult 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 * SUCCESS_NOT_COMPLETE: The image was drawn successfully and completely, but
     26 * it hasn't notified about the sync-decode yet. This can only happen when
     27 * layout pokes at the internal image state beforehand via the result of
     28 * StartDecodingWithResult. This should probably go away eventually, somehow,
     29 * see bug 1471583.
     30 *
     31 * INCOMPLETE: We successfully drew a frame that was partially decoded. (Note
     32 * that successfully drawing a partially decoded frame may not actually draw any
     33 * pixels!) Drawing again with FLAG_SYNC_DECODE would improve the result.
     34 *
     35 * WRONG_SIZE: We successfully drew a wrongly-sized frame that had to be scaled.
     36 * This is only returned if drawing again with FLAG_SYNC_DECODE would improve
     37 * the result; if the size requested was larger than the intrinsic size of the
     38 * image, for example, we would generally have to scale whether FLAG_SYNC_DECODE
     39 * was specified or not, and therefore we would not return WRONG_SIZE.
     40 *
     41 * NOT_READY: We failed to draw because no decoded version of the image was
     42 * available. Drawing again with FLAG_SYNC_DECODE would improve the result.
     43 * (Though FLAG_SYNC_DECODE will not necessarily work until after the image's
     44 * load event!)
     45 *
     46 * TEMPORARY_ERROR: We failed to draw due to a temporary error. Drawing may
     47 * succeed at a later time.
     48 *
     49 * BAD_IMAGE: We failed to draw because the image has an error. This is a
     50 * permanent condition.
     51 *
     52 * BAD_ARGS: We failed to draw because bad arguments were passed to draw().
     53 *
     54 * NOT_SUPPORTED: The requested operation is not supported, but the image is
     55 *                otherwise valid.
     56 */
     57 enum class [[nodiscard]] ImgDrawResult : uint8_t {
     58  SUCCESS,
     59  SUCCESS_NOT_COMPLETE,
     60  INCOMPLETE,
     61  WRONG_SIZE,
     62  NOT_READY,
     63  TEMPORARY_ERROR,
     64  BAD_IMAGE,
     65  BAD_ARGS,
     66  NOT_SUPPORTED
     67 };
     68 
     69 /**
     70 * You can combine ImgDrawResults with &. By analogy to bitwise-&, the result is
     71 * ImgDrawResult::SUCCESS only if both operands are ImgDrawResult::SUCCESS.
     72 * Otherwise, a failing ImgDrawResult is returned; we favor the left operand's
     73 * failure when deciding which failure to return, with the exception that we
     74 * always prefer any other kind of failure over ImgDrawResult::BAD_IMAGE, since
     75 * other failures are recoverable and we want to know if any recoverable
     76 * failures occurred.
     77 */
     78 inline ImgDrawResult operator&(const ImgDrawResult aLeft,
     79                               const ImgDrawResult aRight) {
     80  if (MOZ_LIKELY(aLeft == ImgDrawResult::SUCCESS)) {
     81    return aRight;
     82  }
     83 
     84  if (aLeft == ImgDrawResult::NOT_SUPPORTED ||
     85      aRight == ImgDrawResult::NOT_SUPPORTED) {
     86    return ImgDrawResult::NOT_SUPPORTED;
     87  }
     88 
     89  if ((aLeft == ImgDrawResult::BAD_IMAGE ||
     90       aLeft == ImgDrawResult::SUCCESS_NOT_COMPLETE) &&
     91      aRight != ImgDrawResult::SUCCESS &&
     92      aRight != ImgDrawResult::SUCCESS_NOT_COMPLETE) {
     93    return aRight;
     94  }
     95  return aLeft;
     96 }
     97 
     98 inline ImgDrawResult& operator&=(ImgDrawResult& aLeft,
     99                                 const ImgDrawResult aRight) {
    100  aLeft = aLeft & aRight;
    101  return aLeft;
    102 }
    103 
    104 /**
    105 * A struct used during painting to provide input flags to determine how
    106 * imagelib draw calls should behave and an output ImgDrawResult to return
    107 * information about the result of any imagelib draw calls that may have
    108 * occurred.
    109 */
    110 struct imgDrawingParams {
    111  explicit imgDrawingParams(uint32_t aImageFlags = 0)
    112      : imageFlags(aImageFlags), result(ImgDrawResult::SUCCESS) {}
    113 
    114  const uint32_t imageFlags;  // imgIContainer::FLAG_* image flags to pass to
    115                              // image lib draw calls.
    116  ImgDrawResult result;       // To return results from image lib painting.
    117 };
    118 
    119 }  // namespace image
    120 }  // namespace mozilla
    121 
    122 #endif  // mozilla_image_ImgDrawResult_h