/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * The contents of this file are subject to the Netscape Public License
 * Version 1.0 (the "NPL"); you may not use this file except in
 * compliance with the NPL.  You may obtain a copy of the NPL at
 * http://www.mozilla.org/NPL/
 *
 * Software distributed under the NPL is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
 * for the specific language governing rights and limitations under the
 * NPL.
 *
 * The Initial Developer of this code under the NPL is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
 * Reserved.
 */

/* -*- Mode: C; tab-width: 4 -*-
 *  libimg.h --- API calls to the Image Library.
 *  $Id: libimg.h,v 3.1 1998-03-28 03:34:57 ltabb Exp $
 */


#ifndef _LIBIMG_H
#define _LIBIMG_H
#include "xp_core.h"            /* For XP_BEGIN_PROTOS/XP_END_PROTOS. */
#include "dummy_nc.h"           /* Dummy Net Context */
#include "il_types.h"
#include "MIMGCBIF.h"           /* JMC generated callback interface. */
#include "MIMGCB.h"				/* JMC generated callback interface
                                   implementation. */
#include "MPSIMGCB.h"           /* JMC generated callback interface
                                   implementation for PostScript Front End. */

/*********************** Observers and Observables ***************************/

/* This is the cross-platform observer mechanism.  The image library's client
   should create an XP_ObserverList, and pass it into IL_GetImage().  This
   observer list represents the set of client-provided callbacks to be
   associated with the IL_ImageReq handle returned by IL_GetImage.  Callbacks
   will be invoked with an appropriate message, whenever the image library
   wishes to notify its clients of the availability of information about the
   image or other important changes in the image. The observer list's
   XP_Observable will be set by IL_GetImage, so the XP_ObserverList should be
   created with a NULL observable. */
#include "xp_obs.h"


/**************************** Initialization *********************************/
XP_BEGIN_PROTOS

/* One-time image library initialization.
   - Initialize internal state.
   - Scan image plug-in directory.
   - Register individual image decoders with the netlib. */
extern int
IL_Init(void);

/* Used when exiting the client, this code frees all imagelib data structures.
   This is done for two reasons:
   - It makes leakage analysis of the heap easier.
   - It causes resources to be freed on 16-bit Windows that would otherwise
     persist beyond the program's lifetime. */
extern void
IL_Shutdown(void);


/********************** Image Group Contexts *********************************/

/* Create an IL_GroupContext, which represents an aggregation of state
   for one or more images and which contains an interface to access
   external service functions and callbacks.  IL_NewGroupContext will use
   the IMGCBIF_AddRef callback to increment the reference count for the
   interface.

   The display_context argument is opaque to the image library and is
   passed back to all of the callbacks in IMGCBIF interface. */
extern IL_GroupContext *
IL_NewGroupContext(void *display_context, IMGCBIF *image_callbacks);

/* Free an image context.  IL_DestroyGroupContext will make a call
   to the IMGCBIF_Release callback function of the JMC interface prior to
   releasing the IL_GroupContext structure.  The IMGCBIF_Release callback
   is expected to decrement the reference count for the IMGCBIF interface,
   and to free the callback vtable and the interface structure if the
   reference count is zero. */
extern void
IL_DestroyGroupContext(IL_GroupContext *image_context);

/* Add an observer/closure pair to an image group context's observer list.
   Returns PR_TRUE if the observer is successfully registered. */
extern PRBool
IL_AddGroupObserver(IL_GroupContext *img_cx, XP_ObserverProc observer,
                    void *closure);

/* Remove an observer/closure pair from an image group context's observer
   list.  Returns PR_TRUE if successful. */
extern PRBool
IL_RemoveGroupObserver(IL_GroupContext *img_cx, XP_ObserverProc observer,
                       void *closure);


/************************* Primary API functions *****************************/

/* This is the primary entry point to the imagelib, used to map from a
   URL to a pixmap, fetching and decoding as necessary.

   The width and height parameters specify the target dimensions of
   the image.  The image will be stretched horizontally, vertically or
   both to meet these parameters.  If both width and height are zero,
   the image is decoded using its "natural" size.  If only one of
   width and height is zero, the image is scaled to the provided
   dimension, with the unspecified dimension scaled to maintain the
   image's original aspect ratio.

   If background_color is NULL, a separate mask pixmap will be
   constructed for any transparent images.  If background_color is
   non-NULL, it indicates the RGB value to be painted into the image
   for "transparent" areas of the image, in which case no mask is
   created.  This is intended for backdrops and printing.

   The observable is an opaque pointer that is passed back to observer
   callback functions.

   The following flags may be set when calling IL_GetImage:
   - IL_HIGH_PRIORITY   - For important images, like backdrops.
   - IL_STICKY          - Don't throw this image out of cache.
   - IL_BYPASS_CACHE    - Don't get image out of image cache.
   - IL_ONLY_FROM_CACHE - Don't load if image cache misses.

   The net_group_context is passed back to netlib functions.  It must
   encapsulate the notion of disk cache reload policy which, in
   previous incarnations of this function, was passed in explicitly.
   There is also an assumption being made here that there is some way to
   create a Net Context from this Net Group Context in which Navigator UI
   (animation, status, progress, etc.) can be suppressed.*/
extern IL_ImageReq *
IL_GetImage(const char* url,
            IL_GroupContext *image_context,
            XP_ObserverList observer_list,
            IL_IRGB *background_color,
            uint32 width, uint32 height,
            uint32 flags,
            IL_NetContext *net_context);

/* Release a reference to an image lib request.  If there are no other
   clients of the request's associated pixmap, any related netlib
   activity is terminated and pixmap storage may be reclaimed. */
extern void
IL_DestroyImage (IL_ImageReq *image_req);

/* XXX - This is a new API call to reload all images associated with a
   given IL_GroupContext.  The purpose of this call is to allow all images
   in a document to be reloaded and redecoded to a different bit depth based
   on memory considerations.  This process involves the destruction of the
   old IL_Pixmap structures and the allocation of new structures corresponding
   to the new bit depth. */
extern void
IL_ReloadImages(IL_GroupContext *image_context, IL_NetContext *net_context);

/* Halt decoding of images or animation without destroying associated
   pixmap data.  This may abort any associated netlib streams.  All
   IL_ImageReq's created with the given IL_GroupContext are interrupted. */
extern void
IL_InterruptContext(IL_GroupContext *image_context);

/* Display a rectangular portion of an image.  x and y refer to the top left
   corner of the image, measured in pixels, with respect to the document
   origin.  x_offset and y_offset are measured in pixels, with the
   upper-left-hand corner of the pixmap as the origin, increasing
   left-to-right, top-to-bottom.

   If the width and height values would otherwise cause the sub-image
   to extend off the edge of the source image, the function should
   perform tiling of the source image.  This is used to draw document,
   layer and table cell backdrops.  (Note: it is assumed this case will
   apply only to images which do not require any scaling.)

   If at any time the image library determines that an image request cannot
   be fulfilled or that the image has been delayed, it will notify the client
   synchronously through the observer mechanism.  The client may then choose to
   request that an icon be drawn instead by making a call to IL_DisplayIcon. */
extern void
IL_DisplaySubImage(IL_ImageReq *image_req, int x, int y, int x_offset,
                   int y_offset, int width, int height);

/* Display an icon.  x and y refer to the top left corner of the icon, measured
   in pixels, with respect to the document origin. */
extern void
IL_DisplayIcon(IL_GroupContext *img_cx, int icon_number, int x, int y);

/* Return the dimensions of an icon. */
extern void
IL_GetIconDimensions(IL_GroupContext *img_cx, int icon_number, int *width,
                     int *height);


/********************* Pixmap access functions *******************************/

/* Return the image IL_Pixmap associated with an image request. */
extern IL_Pixmap *
IL_GetImagePixmap(IL_ImageReq *image_req);

/* Return the mask IL_Pixmap associated with an image request. */
extern IL_Pixmap *
IL_GetMaskPixmap(IL_ImageReq *image_req);


/********************* Image query functions *******************************/

/* Return the natural dimensions of the image.  Returns 0,0 if the dimensions
   are unknown. */
extern void
IL_GetNaturalDimensions(IL_ImageReq *image_req, int *width, int *height);


/*********************** Per-context Preferences and Settings ****************/

/* Instruct the Image Library how to render images to the Display Front End.
   The display_flags argument indicates which display settings are to be
   affected.  Flags which may be set include:
   - IL_DISPLAY_CONTEXT     - Set the display context.  Must be compatible with
                              the one used to create the IL_GroupContext.
   - IL_DISPLAY_TYPE        - Set the display type.
   - IL_COLOR_SPACE         - Set the display colorspace.
   - IL_PROGRESSIVE_DISPLAY - Turn progressive display on or off.
   - IL_DITHER_MODE         - Set dither mode.

   The display_data argument provides the required data for the new settings.
   - display_context     - An opaque pointer to the FE's display context.
   - display_type        - IL_Console, IL_Printer, IL_PostScript or
                           IL_MetaFile.
   - color_space         - A pointer to the Display FE's colorspace.
   - progressive_display - Toggle for progressive image display.
   - dither_mode         - IL_ClosestColor, IL_Dither or IL_Auto. */
extern void
IL_SetDisplayMode(IL_GroupContext *image_context, uint32 display_flags,
                  IL_DisplayData *display_data);


/************************ Image format identification ************************/

/* Determine the type of the image, based on the first few bytes of data. */
extern int
IL_Type(const char *buf, int32 len);


/************************ Global imagelib settings ***************************/

/* Set limit on approximate size, in bytes, of all pixmap storage used by the
   Image Library. */
extern void
IL_SetCacheSize(uint32 new_size);


/************************ Memory management **********************************/

/* Free num_bytes of memory by flushing the Least Recently Used (LRU) images
   from the image cache. */
extern void
IL_FreeMemory(IL_GroupContext *image_context, uint32 num_bytes);


/********************** Mac-specific memory-management ***********************/

/* Attempt to release the memory used by a specific image in the image
   cache.  The memory won't be released if the image is still in use
   by one or more clients.  XXX - Can we get rid of this call ?  Why
   the hell do we need this ? */
extern void
IL_UnCache(IL_Pixmap *pixmap);

/* Attempts to release some memory by freeing an image from the image
   cache.  This may not always be possible either because all images
   in the cache are in use or because the cache is empty.  Returns the
   new approximate size of the imagelib cache. */
extern uint32
IL_ShrinkCache(void);

/* Return the approximate storage consumed by the imagelib cache, in bytes */
extern uint32
IL_GetCacheSize(void);


/************************ Miscellaneous garbage ******************************/

/* Returns a pointer to a string containing HTML appropriate for displaying
   in a DocInfo window.  The caller may dispose of the string using XP_FREE. */
extern char *
IL_HTMLImageInfo(char *url_address);

/* Wacky netlib callback designed to give precedence to streams that block
   layout. */
extern PRBool
IL_PreferredStream(IL_URL *urls);

/* This is a legacy "safety-valve" routine, called each time a new HTML page
   is loaded.  It causes remaining references to images in the given group
   context to be freed, i.e. like calling IL_DestroyImage on each of them.
   This is primarily required because layout sometimes leaks images, and it
   should go away when we can fix layout. */
extern void
IL_DestroyImageGroup(IL_GroupContext *image_context);

XP_END_PROTOS
#endif /* _LIBIMG_H */



