image/src/imgDecoderObserver.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_IMAGELIB_IMGDECODEROBSERVER_H_
   7 #define MOZILLA_IMAGELIB_IMGDECODEROBSERVER_H_
   8
   9 #include "nsRect.h"
  10 #include "mozilla/WeakPtr.h"
  11
  12 struct nsIntRect;
  13
  14 /**
  15  * imgDecoderObserver interface
  16  *
  17  * This interface is used to observe Decoder objects.
  18  *
  19  * We make the distinction here between "load" and "decode" notifications. Load
  20  * notifications are fired as the image is loaded from the network or
  21  * filesystem. Decode notifications are fired as the image is decoded. If an
  22  * image is decoded on load and not visibly discarded, decode notifications are
  23  * nested logically inside load notifications as one might expect. However, with
  24  * decode-on-draw, the set of decode notifications can come completely _after_
  25  * the load notifications, and can come multiple times if the image is
  26  * discardable. Moreover, they can be interleaved in various ways. In general,
  27  * any presumed ordering between load and decode notifications should not be
  28  * relied upon.
  29  *
  30  * Decode notifications may or may not be synchronous, depending on the
  31  * situation. If imgIDecoder::FLAG_SYNC_DECODE is passed to a function that
  32  * triggers a decode, all notifications that can be generated from the currently
  33  * loaded data fire before the call returns. If FLAG_SYNC_DECODE is not passed,
  34  * all, some, or none of the notifications may fire before the call returns.
  35  */
  36 class imgDecoderObserver
  37 {
  38 public:
  39   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(imgDecoderObserver);
  40
  41   /**
  42    * Load notification.
  43    *
  44    * called at the same time that nsIRequestObserver::onStartRequest would be
  45    * (used only for observers of imgIRequest objects, which are nsIRequests,
  46    * not imgIDecoder objects)
  47    */
  48   virtual void OnStartRequest() = 0;
  49
  50   /**
  51    * Decode notification.
  52    *
  53    * Called as soon as the image begins getting decoded. This does not include
  54    * "header-only" decodes used by decode-on-draw to parse the width/height
  55    * out of the image. Thus, it is a decode notification only.
  56    */
  57   virtual void OnStartDecode() = 0;
  58
  59   /**
  60    * Load notification.
  61    *
  62    * Called once enough data has been loaded from the network that we were able
  63    * to parse the width/height from the image. By the time this callback is been
  64    * called, the size has been set on the container and STATUS_SIZE_AVAILABLE
  65    * has been set on the associated imgRequest.
  66    */
  67   virtual void OnStartContainer() = 0;
  68
  69   /**
  70    * Decode notification.
  71    *
  72    * Called when we know a frame has begun decoding.
  73    */
  74   virtual void OnStartFrame() = 0;
  75
  76   /**
  77    * Decode notification.
  78    *
  79    * called when there is more to paint.
  80    */
  81   virtual void FrameChanged(const nsIntRect * aDirtyRect) = 0;
  82
  83   /**
  84    * Decode notification.
  85    *
  86    * called when a frame is finished decoding.
  87    */
  88   virtual void OnStopFrame() = 0;
  89
  90   /**
  91    * Notification for when an image is known to be animated. This should be
  92    * fired at the earliest possible time.
  93    */
  94   virtual void OnImageIsAnimated() = 0;
  95
  96   /**
  97    * Decode notification.
  98    *
  99    * Called when all decoding has terminated.
 100    */
 101   virtual void OnStopDecode(nsresult status) = 0;
 102
 103   /**
 104    * Load notification.
 105    *
 106    * called at the same time that nsIRequestObserver::onStopRequest would be
 107    * (used only for observers of imgIRequest objects, which are nsIRequests,
 108    * not imgIDecoder objects)
 109    */
 110   virtual void OnStopRequest(bool aIsLastPart, nsresult aStatus) = 0;
 111
 112   /**
 113    * Called when the decoded image data is discarded. This means that the frames
 114    * no longer exist in decoded form, and any attempt to access or draw the
 115    * image will initiate a new series of progressive decode notifications.
 116    */
 117   virtual void OnDiscard() = 0;
 118
 119   /**
 120    * Called when we are asked to Draw an image that is not locked.
 121    */
 122   virtual void OnUnlockedDraw() = 0;
 123
 124   /**
 125    * Called when an image is realized to be in error state.
 126    */
 127   virtual void OnError() = 0;
 128
 129 protected:
 130   virtual ~imgDecoderObserver() = 0;
 131 };
 132
 133 // We must define a destructor because derived classes call our destructor from
 134 // theirs.  Pure virtual destructors only requires that child classes implement
 135 // a virtual destructor, not that we can't have one too!
 136 inline imgDecoderObserver::~imgDecoderObserver()
 137 {}
 138
 139 #endif // MOZILLA_IMAGELIB_IMGDECODEROBSERVER_H