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: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIURI;
michael@0: 
michael@0: [function, scriptable, uuid(e4089e21-71b6-40af-b546-33c21b90e874)]
michael@0: interface mozIRepresentativeColorCallback : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Will be called when color analysis finishes.
michael@0:    *
michael@0:    * @param success
michael@0:    *        True if analysis was successful, false otherwise.
michael@0:    *        Analysis can fail if the image is transparent, imageURI doesn't
michael@0:    *        resolve to a valid image, or the image is too big.
michael@0:    *
michael@0:    * @param color
michael@0:    *        The representative color as an integer in RGB form.
michael@0:    *        e.g. 0xFF0102 == rgb(255,1,2)
michael@0:    *        If success is false, color is not provided.
michael@0:    */
michael@0:   void onComplete(in boolean success, [optional] in unsigned long color);
michael@0: };
michael@0: 
michael@0: [scriptable, uuid(d056186c-28a0-494e-aacc-9e433772b143)]
michael@0: interface mozIColorAnalyzer : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Given an image URI, find the most representative color for that image
michael@0:    * based on the frequency of each color.  Preference is given to colors that
michael@0:    * are more interesting.  Avoids the background color if it can be
michael@0:    * discerned.  Ignores sufficiently transparent colors.
michael@0:    *
michael@0:    * This is intended to be used on favicon images.  Larger images take longer
michael@0:    * to process, especially those with a larger number of unique colors.  If
michael@0:    * imageURI points to an image that has more than 128^2 pixels, this method
michael@0:    * will fail before analyzing it for performance reasons.
michael@0:    *
michael@0:    * @param imageURI
michael@0:    *        A URI pointing to the image - ideally a data: URI, but any scheme
michael@0:    *        that will load when setting the src attribute of a DOM img element
michael@0:    *        should work.
michael@0:    * @param callback
michael@0:    *        Function to call when the representative color is found or an
michael@0:    *        error occurs.
michael@0:    */
michael@0:   void findRepresentativeColor(in nsIURI imageURI,
michael@0:                                in mozIRepresentativeColorCallback callback);
michael@0: };