michael@0: /** -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
michael@0:  * This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef MOZILLA_IMAGELIB_IMGDECODEROBSERVER_H_
michael@0: #define MOZILLA_IMAGELIB_IMGDECODEROBSERVER_H_
michael@0: 
michael@0: #include "nsRect.h"
michael@0: #include "mozilla/WeakPtr.h"
michael@0: 
michael@0: struct nsIntRect;
michael@0: 
michael@0: /**
michael@0:  * imgDecoderObserver interface
michael@0:  *
michael@0:  * This interface is used to observe Decoder objects.
michael@0:  *
michael@0:  * We make the distinction here between "load" and "decode" notifications. Load
michael@0:  * notifications are fired as the image is loaded from the network or
michael@0:  * filesystem. Decode notifications are fired as the image is decoded. If an
michael@0:  * image is decoded on load and not visibly discarded, decode notifications are
michael@0:  * nested logically inside load notifications as one might expect. However, with
michael@0:  * decode-on-draw, the set of decode notifications can come completely _after_
michael@0:  * the load notifications, and can come multiple times if the image is
michael@0:  * discardable. Moreover, they can be interleaved in various ways. In general,
michael@0:  * any presumed ordering between load and decode notifications should not be
michael@0:  * relied upon.
michael@0:  *
michael@0:  * Decode notifications may or may not be synchronous, depending on the
michael@0:  * situation. If imgIDecoder::FLAG_SYNC_DECODE is passed to a function that
michael@0:  * triggers a decode, all notifications that can be generated from the currently
michael@0:  * loaded data fire before the call returns. If FLAG_SYNC_DECODE is not passed,
michael@0:  * all, some, or none of the notifications may fire before the call returns.
michael@0:  */
michael@0: class imgDecoderObserver
michael@0: {
michael@0: public:
michael@0:   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(imgDecoderObserver);
michael@0: 
michael@0:   /**
michael@0:    * Load notification.
michael@0:    *
michael@0:    * called at the same time that nsIRequestObserver::onStartRequest would be
michael@0:    * (used only for observers of imgIRequest objects, which are nsIRequests,
michael@0:    * not imgIDecoder objects)
michael@0:    */
michael@0:   virtual void OnStartRequest() = 0;
michael@0: 
michael@0:   /**
michael@0:    * Decode notification.
michael@0:    *
michael@0:    * Called as soon as the image begins getting decoded. This does not include
michael@0:    * "header-only" decodes used by decode-on-draw to parse the width/height
michael@0:    * out of the image. Thus, it is a decode notification only.
michael@0:    */
michael@0:   virtual void OnStartDecode() = 0;
michael@0: 
michael@0:   /**
michael@0:    * Load notification.
michael@0:    *
michael@0:    * Called once enough data has been loaded from the network that we were able
michael@0:    * to parse the width/height from the image. By the time this callback is been
michael@0:    * called, the size has been set on the container and STATUS_SIZE_AVAILABLE
michael@0:    * has been set on the associated imgRequest.
michael@0:    */
michael@0:   virtual void OnStartContainer() = 0;
michael@0: 
michael@0:   /**
michael@0:    * Decode notification.
michael@0:    *
michael@0:    * Called when we know a frame has begun decoding.
michael@0:    */
michael@0:   virtual void OnStartFrame() = 0;
michael@0: 
michael@0:   /**
michael@0:    * Decode notification.
michael@0:    *
michael@0:    * called when there is more to paint.
michael@0:    */
michael@0:   virtual void FrameChanged(const nsIntRect * aDirtyRect) = 0;
michael@0: 
michael@0:   /**
michael@0:    * Decode notification.
michael@0:    *
michael@0:    * called when a frame is finished decoding.
michael@0:    */
michael@0:   virtual void OnStopFrame() = 0;
michael@0: 
michael@0:   /**
michael@0:    * Notification for when an image is known to be animated. This should be
michael@0:    * fired at the earliest possible time.
michael@0:    */
michael@0:   virtual void OnImageIsAnimated() = 0;
michael@0: 
michael@0:   /**
michael@0:    * Decode notification.
michael@0:    *
michael@0:    * Called when all decoding has terminated.
michael@0:    */
michael@0:   virtual void OnStopDecode(nsresult status) = 0;
michael@0: 
michael@0:   /**
michael@0:    * Load notification.
michael@0:    *
michael@0:    * called at the same time that nsIRequestObserver::onStopRequest would be
michael@0:    * (used only for observers of imgIRequest objects, which are nsIRequests,
michael@0:    * not imgIDecoder objects)
michael@0:    */
michael@0:   virtual void OnStopRequest(bool aIsLastPart, nsresult aStatus) = 0;
michael@0: 
michael@0:   /**
michael@0:    * Called when the decoded image data is discarded. This means that the frames
michael@0:    * no longer exist in decoded form, and any attempt to access or draw the
michael@0:    * image will initiate a new series of progressive decode notifications.
michael@0:    */
michael@0:   virtual void OnDiscard() = 0;
michael@0: 
michael@0:   /**
michael@0:    * Called when we are asked to Draw an image that is not locked.
michael@0:    */
michael@0:   virtual void OnUnlockedDraw() = 0;
michael@0: 
michael@0:   /**
michael@0:    * Called when an image is realized to be in error state.
michael@0:    */
michael@0:   virtual void OnError() = 0;
michael@0: 
michael@0: protected:
michael@0:   virtual ~imgDecoderObserver() = 0;
michael@0: };
michael@0: 
michael@0: // We must define a destructor because derived classes call our destructor from
michael@0: // theirs.  Pure virtual destructors only requires that child classes implement
michael@0: // a virtual destructor, not that we can't have one too!
michael@0: inline imgDecoderObserver::~imgDecoderObserver()
michael@0: {}
michael@0: 
michael@0: #endif // MOZILLA_IMAGELIB_IMGDECODEROBSERVER_H