home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / modules / libimg / public / libimg.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  13.2 KB  |  311 lines
  1. /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2.  *
  3.  * The contents of this file are subject to the Netscape Public License
  4.  * Version 1.0 (the "NPL"); you may not use this file except in
  5.  * compliance with the NPL.  You may obtain a copy of the NPL at
  6.  * http://www.mozilla.org/NPL/
  7.  *
  8.  * Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  * for the specific language governing rights and limitations under the
  11.  * NPL.
  12.  *
  13.  * The Initial Developer of this code under the NPL is Netscape
  14.  * Communications Corporation.  Portions created by Netscape are
  15.  * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  * Reserved.
  17.  */
  18.  
  19. /* -*- Mode: C; tab-width: 4 -*-
  20.  *  libimg.h --- API calls to the Image Library.
  21.  *  $Id: libimg.h,v 3.1 1998/03/28 03:34:57 ltabb Exp $
  22.  */
  23.  
  24.  
  25. #ifndef _LIBIMG_H
  26. #define _LIBIMG_H
  27. #include "xp_core.h"            /* For XP_BEGIN_PROTOS/XP_END_PROTOS. */
  28. #include "dummy_nc.h"           /* Dummy Net Context */
  29. #include "il_types.h"
  30. #include "MIMGCBIF.h"           /* JMC generated callback interface. */
  31. #include "MIMGCB.h"                /* JMC generated callback interface
  32.                                    implementation. */
  33. #include "MPSIMGCB.h"           /* JMC generated callback interface
  34.                                    implementation for PostScript Front End. */
  35.  
  36. /*********************** Observers and Observables ***************************/
  37.  
  38. /* This is the cross-platform observer mechanism.  The image library's client
  39.    should create an XP_ObserverList, and pass it into IL_GetImage().  This
  40.    observer list represents the set of client-provided callbacks to be
  41.    associated with the IL_ImageReq handle returned by IL_GetImage.  Callbacks
  42.    will be invoked with an appropriate message, whenever the image library
  43.    wishes to notify its clients of the availability of information about the
  44.    image or other important changes in the image. The observer list's
  45.    XP_Observable will be set by IL_GetImage, so the XP_ObserverList should be
  46.    created with a NULL observable. */
  47. #include "xp_obs.h"
  48.  
  49.  
  50. /**************************** Initialization *********************************/
  51. XP_BEGIN_PROTOS
  52.  
  53. /* One-time image library initialization.
  54.    - Initialize internal state.
  55.    - Scan image plug-in directory.
  56.    - Register individual image decoders with the netlib. */
  57. extern int
  58. IL_Init(void);
  59.  
  60. /* Used when exiting the client, this code frees all imagelib data structures.
  61.    This is done for two reasons:
  62.    - It makes leakage analysis of the heap easier.
  63.    - It causes resources to be freed on 16-bit Windows that would otherwise
  64.      persist beyond the program's lifetime. */
  65. extern void
  66. IL_Shutdown(void);
  67.  
  68.  
  69. /********************** Image Group Contexts *********************************/
  70.  
  71. /* Create an IL_GroupContext, which represents an aggregation of state
  72.    for one or more images and which contains an interface to access
  73.    external service functions and callbacks.  IL_NewGroupContext will use
  74.    the IMGCBIF_AddRef callback to increment the reference count for the
  75.    interface.
  76.  
  77.    The display_context argument is opaque to the image library and is
  78.    passed back to all of the callbacks in IMGCBIF interface. */
  79. extern IL_GroupContext *
  80. IL_NewGroupContext(void *display_context, IMGCBIF *image_callbacks);
  81.  
  82. /* Free an image context.  IL_DestroyGroupContext will make a call
  83.    to the IMGCBIF_Release callback function of the JMC interface prior to
  84.    releasing the IL_GroupContext structure.  The IMGCBIF_Release callback
  85.    is expected to decrement the reference count for the IMGCBIF interface,
  86.    and to free the callback vtable and the interface structure if the
  87.    reference count is zero. */
  88. extern void
  89. IL_DestroyGroupContext(IL_GroupContext *image_context);
  90.  
  91. /* Add an observer/closure pair to an image group context's observer list.
  92.    Returns PR_TRUE if the observer is successfully registered. */
  93. extern PRBool
  94. IL_AddGroupObserver(IL_GroupContext *img_cx, XP_ObserverProc observer,
  95.                     void *closure);
  96.  
  97. /* Remove an observer/closure pair from an image group context's observer
  98.    list.  Returns PR_TRUE if successful. */
  99. extern PRBool
  100. IL_RemoveGroupObserver(IL_GroupContext *img_cx, XP_ObserverProc observer,
  101.                        void *closure);
  102.  
  103.  
  104. /************************* Primary API functions *****************************/
  105.  
  106. /* This is the primary entry point to the imagelib, used to map from a
  107.    URL to a pixmap, fetching and decoding as necessary.
  108.  
  109.    The width and height parameters specify the target dimensions of
  110.    the image.  The image will be stretched horizontally, vertically or
  111.    both to meet these parameters.  If both width and height are zero,
  112.    the image is decoded using its "natural" size.  If only one of
  113.    width and height is zero, the image is scaled to the provided
  114.    dimension, with the unspecified dimension scaled to maintain the
  115.    image's original aspect ratio.
  116.  
  117.    If background_color is NULL, a separate mask pixmap will be
  118.    constructed for any transparent images.  If background_color is
  119.    non-NULL, it indicates the RGB value to be painted into the image
  120.    for "transparent" areas of the image, in which case no mask is
  121.    created.  This is intended for backdrops and printing.
  122.  
  123.    The observable is an opaque pointer that is passed back to observer
  124.    callback functions.
  125.  
  126.    The following flags may be set when calling IL_GetImage:
  127.    - IL_HIGH_PRIORITY   - For important images, like backdrops.
  128.    - IL_STICKY          - Don't throw this image out of cache.
  129.    - IL_BYPASS_CACHE    - Don't get image out of image cache.
  130.    - IL_ONLY_FROM_CACHE - Don't load if image cache misses.
  131.  
  132.    The net_group_context is passed back to netlib functions.  It must
  133.    encapsulate the notion of disk cache reload policy which, in
  134.    previous incarnations of this function, was passed in explicitly.
  135.    There is also an assumption being made here that there is some way to
  136.    create a Net Context from this Net Group Context in which Navigator UI
  137.    (animation, status, progress, etc.) can be suppressed.*/
  138. extern IL_ImageReq *
  139. IL_GetImage(const char* url,
  140.             IL_GroupContext *image_context,
  141.             XP_ObserverList observer_list,
  142.             IL_IRGB *background_color,
  143.             uint32 width, uint32 height,
  144.             uint32 flags,
  145.             IL_NetContext *net_context);
  146.  
  147. /* Release a reference to an image lib request.  If there are no other
  148.    clients of the request's associated pixmap, any related netlib
  149.    activity is terminated and pixmap storage may be reclaimed. */
  150. extern void
  151. IL_DestroyImage (IL_ImageReq *image_req);
  152.  
  153. /* XXX - This is a new API call to reload all images associated with a
  154.    given IL_GroupContext.  The purpose of this call is to allow all images
  155.    in a document to be reloaded and redecoded to a different bit depth based
  156.    on memory considerations.  This process involves the destruction of the
  157.    old IL_Pixmap structures and the allocation of new structures corresponding
  158.    to the new bit depth. */
  159. extern void
  160. IL_ReloadImages(IL_GroupContext *image_context, IL_NetContext *net_context);
  161.  
  162. /* Halt decoding of images or animation without destroying associated
  163.    pixmap data.  This may abort any associated netlib streams.  All
  164.    IL_ImageReq's created with the given IL_GroupContext are interrupted. */
  165. extern void
  166. IL_InterruptContext(IL_GroupContext *image_context);
  167.  
  168. /* Display a rectangular portion of an image.  x and y refer to the top left
  169.    corner of the image, measured in pixels, with respect to the document
  170.    origin.  x_offset and y_offset are measured in pixels, with the
  171.    upper-left-hand corner of the pixmap as the origin, increasing
  172.    left-to-right, top-to-bottom.
  173.  
  174.    If the width and height values would otherwise cause the sub-image
  175.    to extend off the edge of the source image, the function should
  176.    perform tiling of the source image.  This is used to draw document,
  177.    layer and table cell backdrops.  (Note: it is assumed this case will
  178.    apply only to images which do not require any scaling.)
  179.  
  180.    If at any time the image library determines that an image request cannot
  181.    be fulfilled or that the image has been delayed, it will notify the client
  182.    synchronously through the observer mechanism.  The client may then choose to
  183.    request that an icon be drawn instead by making a call to IL_DisplayIcon. */
  184. extern void
  185. IL_DisplaySubImage(IL_ImageReq *image_req, int x, int y, int x_offset,
  186.                    int y_offset, int width, int height);
  187.  
  188. /* Display an icon.  x and y refer to the top left corner of the icon, measured
  189.    in pixels, with respect to the document origin. */
  190. extern void
  191. IL_DisplayIcon(IL_GroupContext *img_cx, int icon_number, int x, int y);
  192.  
  193. /* Return the dimensions of an icon. */
  194. extern void
  195. IL_GetIconDimensions(IL_GroupContext *img_cx, int icon_number, int *width,
  196.                      int *height);
  197.  
  198.  
  199. /********************* Pixmap access functions *******************************/
  200.  
  201. /* Return the image IL_Pixmap associated with an image request. */
  202. extern IL_Pixmap *
  203. IL_GetImagePixmap(IL_ImageReq *image_req);
  204.  
  205. /* Return the mask IL_Pixmap associated with an image request. */
  206. extern IL_Pixmap *
  207. IL_GetMaskPixmap(IL_ImageReq *image_req);
  208.  
  209.  
  210. /********************* Image query functions *******************************/
  211.  
  212. /* Return the natural dimensions of the image.  Returns 0,0 if the dimensions
  213.    are unknown. */
  214. extern void
  215. IL_GetNaturalDimensions(IL_ImageReq *image_req, int *width, int *height);
  216.  
  217.  
  218. /*********************** Per-context Preferences and Settings ****************/
  219.  
  220. /* Instruct the Image Library how to render images to the Display Front End.
  221.    The display_flags argument indicates which display settings are to be
  222.    affected.  Flags which may be set include:
  223.    - IL_DISPLAY_CONTEXT     - Set the display context.  Must be compatible with
  224.                               the one used to create the IL_GroupContext.
  225.    - IL_DISPLAY_TYPE        - Set the display type.
  226.    - IL_COLOR_SPACE         - Set the display colorspace.
  227.    - IL_PROGRESSIVE_DISPLAY - Turn progressive display on or off.
  228.    - IL_DITHER_MODE         - Set dither mode.
  229.  
  230.    The display_data argument provides the required data for the new settings.
  231.    - display_context     - An opaque pointer to the FE's display context.
  232.    - display_type        - IL_Console, IL_Printer, IL_PostScript or
  233.                            IL_MetaFile.
  234.    - color_space         - A pointer to the Display FE's colorspace.
  235.    - progressive_display - Toggle for progressive image display.
  236.    - dither_mode         - IL_ClosestColor, IL_Dither or IL_Auto. */
  237. extern void
  238. IL_SetDisplayMode(IL_GroupContext *image_context, uint32 display_flags,
  239.                   IL_DisplayData *display_data);
  240.  
  241.  
  242. /************************ Image format identification ************************/
  243.  
  244. /* Determine the type of the image, based on the first few bytes of data. */
  245. extern int
  246. IL_Type(const char *buf, int32 len);
  247.  
  248.  
  249. /************************ Global imagelib settings ***************************/
  250.  
  251. /* Set limit on approximate size, in bytes, of all pixmap storage used by the
  252.    Image Library. */
  253. extern void
  254. IL_SetCacheSize(uint32 new_size);
  255.  
  256.  
  257. /************************ Memory management **********************************/
  258.  
  259. /* Free num_bytes of memory by flushing the Least Recently Used (LRU) images
  260.    from the image cache. */
  261. extern void
  262. IL_FreeMemory(IL_GroupContext *image_context, uint32 num_bytes);
  263.  
  264.  
  265. /********************** Mac-specific memory-management ***********************/
  266.  
  267. /* Attempt to release the memory used by a specific image in the image
  268.    cache.  The memory won't be released if the image is still in use
  269.    by one or more clients.  XXX - Can we get rid of this call ?  Why
  270.    the hell do we need this ? */
  271. extern void
  272. IL_UnCache(IL_Pixmap *pixmap);
  273.  
  274. /* Attempts to release some memory by freeing an image from the image
  275.    cache.  This may not always be possible either because all images
  276.    in the cache are in use or because the cache is empty.  Returns the
  277.    new approximate size of the imagelib cache. */
  278. extern uint32
  279. IL_ShrinkCache(void);
  280.  
  281. /* Return the approximate storage consumed by the imagelib cache, in bytes */
  282. extern uint32
  283. IL_GetCacheSize(void);
  284.  
  285.  
  286. /************************ Miscellaneous garbage ******************************/
  287.  
  288. /* Returns a pointer to a string containing HTML appropriate for displaying
  289.    in a DocInfo window.  The caller may dispose of the string using XP_FREE. */
  290. extern char *
  291. IL_HTMLImageInfo(char *url_address);
  292.  
  293. /* Wacky netlib callback designed to give precedence to streams that block
  294.    layout. */
  295. extern PRBool
  296. IL_PreferredStream(IL_URL *urls);
  297.  
  298. /* This is a legacy "safety-valve" routine, called each time a new HTML page
  299.    is loaded.  It causes remaining references to images in the given group
  300.    context to be freed, i.e. like calling IL_DestroyImage on each of them.
  301.    This is primarily required because layout sometimes leaks images, and it
  302.    should go away when we can fix layout. */
  303. extern void
  304. IL_DestroyImageGroup(IL_GroupContext *image_context);
  305.  
  306. XP_END_PROTOS
  307. #endif /* _LIBIMG_H */
  308.  
  309.  
  310.  
  311.