home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / jreheadf.zip / jawt.h < prev    next >
C/C++ Source or Header  |  2002-08-31  |  9KB  |  285 lines
  1. /*
  2.  * @(#)src/contract/awt/sov/jawt.h, awt, as131, 20020829 1.5.2.1
  3.  * ===========================================================================
  4.  * Licensed Materials - Property of IBM
  5.  * "Restricted Materials of IBM"
  6.  *
  7.  * IBM Java(tm)2 SDK, Standard Edition, v 1.3.1
  8.  * (C) Copyright IBM Corp. 1998, 2001. All Rights Reserved
  9.  * US Government Users Restricted Rights - Use, duplication or disclosure
  10.  * restricted by GSA ADP Schedule Contract with IBM Corp.
  11.  * ===========================================================================
  12.  */
  13.  
  14. /* 
  15.  *
  16.  * ===========================================================================
  17.  *
  18.  *
  19.  * Copyright 1999, 2000 Sun Microsystems, Inc. All Rights Reserved.
  20.  *
  21.  * ===========================================================================
  22.  * Change activity:
  23.  *
  24.  * Reason  Date   Origin    Description
  25.  * ------  ----   ------    -------------------------------------------------- 
  26.  * 31653   240401 mchapman  Add IBM module header 
  27.  *
  28.  * ===========================================================================
  29.  * Module Information:
  30.  * 
  31.  * DESCRIPTION: IBM.WRITEME
  32.  * ===========================================================================
  33.  */
  34.  
  35. /*
  36.  * @(#)jawt.h    1.2 99/05/27
  37.  *
  38.  * Copyright 1999 by Sun Microsystems, Inc.,
  39.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  40.  * All rights reserved.
  41.  *
  42.  */
  43.  
  44. #ifndef _JAVASOFT_JAWT_H_
  45. #define _JAVASOFT_JAWT_H_
  46.  
  47. #include "jni.h"
  48.  
  49. #ifdef __cplusplus
  50. extern "C" {
  51. #endif
  52.  
  53. /*
  54.  * AWT native interface (new in JDK 1.3)
  55.  *
  56.  * The AWT native interface allows a native C or C++ application a means
  57.  * by which to access native structures in AWT.     This is to facilitate moving
  58.  * legacy C and C++ applications to Java and to target the needs of the
  59.  * community who, at present, wish to do their own native rendering to canvases
  60.  * for performance reasons.  Standard extensions such as Java3D also require a
  61.  * means to access the underlying native data structures of AWT.
  62.  *
  63.  * There may be future extensions to this API depending on demand.
  64.  *
  65.  * A VM does not have to implement this API in order to pass the JCK.
  66.  * It is recommended, however, that this API is implemented on VMs that support
  67.  * standard extensions, such as Java3D.
  68.  *
  69.  * Since this is a native API, any program which uses it cannot be considered
  70.  * 100% pure java.
  71.  */
  72.  
  73. /*
  74.  * AWT Native Drawing Surface (JAWT_DrawingSurface).
  75.  *
  76.  * For each platform, there is a native drawing surface structure.  This
  77.  * platform-specific structure can be found in jawt_md.h.  It is recommended
  78.  * that additional platforms follow the same model.  It is also recommended
  79.  * that VMs on Win32 and Solaris support the existing structures in jawt_md.h.
  80.  *
  81.  *******************
  82.  * EXAMPLE OF USAGE:
  83.  *******************
  84.  *
  85.  * In Win32, a programmer wishes to access the HWND of a canvas to perform
  86.  * native rendering into it.  The programmer has declared the paint() method
  87.  * for their canvas subclass to be native:
  88.  *
  89.  *
  90.  * MyCanvas.java:
  91.  *
  92.  * import java.awt.*;
  93.  *
  94.  * public class MyCanvas extends Canvas {
  95.  *
  96.  *     static {
  97.  *       System.loadLibrary("mylib");
  98.  *     }
  99.  *
  100.  *     public native void paint(Graphics g);
  101.  * }
  102.  *
  103.  *
  104.  * myfile.c:
  105.  *
  106.  * #include "jawt_md.h"
  107.  * #include <assert.h>
  108.  *
  109.  * JNIEXPORT void JNICALL
  110.  * Java_MyCanvas_paint(JNIEnv* env, jobject canvas, jobject graphics)
  111.  * {
  112.  *     JAWT awt;
  113.  *     JAWT_DrawingSurface* ds;
  114.  *     JAWT_DrawingSurfaceInfo* dsi;
  115.  *     JAWT_Win32DrawingSurfaceInfo* dsi_win;
  116.  *     jboolean result;
  117.  *     jint lock;
  118.  *
  119.  *     // Get the AWT
  120.  *     awt.version = JAWT_VERSION_1_3;
  121.  *     result = JAWT_GetAWT(env, &awt);
  122.  *     assert(result != JNI_FALSE);
  123.  *
  124.  *     // Get the drawing surface
  125.  *     ds = awt.GetDrawingSurface(env, canvas);
  126.  *     assert(ds != NULL);
  127.  *
  128.  *     // Lock the drawing surface
  129.  *     lock = ds->Lock(ds);
  130.  *     assert((lock & JAWT_LOCK_ERROR) == 0);
  131.  *
  132.  *     // Get the drawing surface info
  133.  *     dsi = ds->GetDrawingSurfaceInfo(ds);
  134.  *
  135.  *     // Get the platform-specific drawing info
  136.  *     dsi_win = (JAWT_Win32DrawingSurfaceInfo*)dsi->platformInfo;
  137.  *
  138.  *     //////////////////////////////
  139.  *     // !!! DO PAINTING HERE !!! //
  140.  *     //////////////////////////////
  141.  *
  142.  *     // Free the drawing surface info
  143.  *     ds->FreeDrawingSurfaceInfo(dsi);
  144.  *
  145.  *     // Unlock the drawing surface
  146.  *     ds->Unlock(ds);
  147.  *
  148.  *     // Free the drawing surface
  149.  *     awt.FreeDrawingSurface(ds);
  150.  * }
  151.  *
  152.  */
  153.  
  154. /*
  155.  * JAWT_Rectangle
  156.  * Structure for a native rectangle.
  157.  */
  158. typedef struct jawt_Rectangle {
  159.     jint x;
  160.     jint y;
  161.     jint width;
  162.     jint height;
  163. } JAWT_Rectangle;
  164.  
  165. struct jawt_DrawingSurface;
  166.  
  167. /*
  168.  * JAWT_DrawingSurfaceInfo
  169.  * Structure for containing the underlying drawing information of a component.
  170.  */
  171. typedef struct jawt_DrawingSurfaceInfo {
  172.     /*
  173.      * Pointer to the platform-specific information.  This can be safely
  174.      * cast to a JAWT_Win32DrawingSurfaceInfo on Windows or a
  175.      * JAWT_X11DrawingSurfaceInfo on Solaris.  See jawt_md.h for details.
  176.      */
  177.     void* platformInfo;
  178.     /* Cached pointer to the underlying drawing surface */
  179.     struct jawt_DrawingSurface* ds;
  180.     /* Bounding rectangle of the drawing surface */
  181.     JAWT_Rectangle bounds;
  182.     /* Number of rectangles in the clip */
  183.     jint clipSize;
  184.     /* Clip rectangle array */
  185.     JAWT_Rectangle* clip;
  186. } JAWT_DrawingSurfaceInfo;
  187.  
  188. #define JAWT_LOCK_ERROR            0x00000001
  189. #define JAWT_LOCK_CLIP_CHANGED        0x00000002
  190. #define JAWT_LOCK_BOUNDS_CHANGED    0x00000004
  191. #define JAWT_LOCK_SURFACE_CHANGED    0x00000008
  192.  
  193. /*
  194.  * JAWT_DrawingSurface
  195.  * Structure for containing the underlying drawing information of a component.
  196.  * All operations on a JAWT_DrawingSurface MUST be performed from the same
  197.  * thread as the call to GetDrawingSurface.
  198.  */
  199. typedef struct jawt_DrawingSurface {
  200.     /* Cached reference to the Java environment of the calling thread */
  201.     JNIEnv* env;
  202.     /* Cached reference to the target object */
  203.     jobject target;
  204.     /*
  205.      * Lock the surface of the target component for native rendering.
  206.      * When finished drawing, the surface must be unlocked with
  207.      * Unlock().  This function returns a bitmask with one or more of the
  208.      * following values:
  209.      *
  210.      * JAWT_LOCK_ERROR - When an error has occurred and the surface could not
  211.      * be locked.
  212.      *
  213.      * JAWT_LOCK_CLIP_CHANGED - When the clip region has changed.
  214.      *
  215.      * JAWT_LOCK_BOUNDS_CHANGED - When the bounds of the surface have changed.
  216.      *
  217.      * JAWT_LOCK_SURFACE_CHANGED - When the surface itself has changed
  218.      */
  219.     jint (JNICALL *Lock)
  220.     (struct jawt_DrawingSurface* ds);
  221.     /*
  222.      * Get the drawing surface info.
  223.      * The value returned may be cached, but the values may change if
  224.      * additional calls to Lock() or Unlock() are made.
  225.      * Lock() must be called before this can return a valid value.
  226.      * Returns NULL if an error has occurred.
  227.      * When finished with the returned value, FreeDrawingSurfaceInfo must be
  228.      * called.
  229.      */
  230.     JAWT_DrawingSurfaceInfo* (JNICALL *GetDrawingSurfaceInfo)
  231.     (struct jawt_DrawingSurface* ds);
  232.     /*
  233.      * Free the drawing surface info.
  234.      */
  235.     void (JNICALL *FreeDrawingSurfaceInfo)
  236.     (JAWT_DrawingSurfaceInfo* dsi);
  237.     /*
  238.      * Unlock the drawing surface of the target component for native rendering.
  239.      */
  240.     void (JNICALL *Unlock)
  241.     (struct jawt_DrawingSurface* ds);
  242. } JAWT_DrawingSurface;
  243.  
  244. /*
  245.  * JAWT
  246.  * Structure for containing native AWT functions.
  247.  */
  248. typedef struct jawt {
  249.     /*
  250.      * Version of this structure.  This must always be set before
  251.      * calling JAWT_GetAWT()
  252.      */
  253.     jint version;
  254.     /*
  255.      * Return a drawing surface from a target jobject.    This value
  256.      * may be cached.
  257.      * Returns NULL if an error has occurred.
  258.      * Target must be a java.awt.Canvas.
  259.      * FreeDrawingSurface() must be called when finished with the
  260.      * returned JAWT_DrawingSurface.
  261.      */
  262.     JAWT_DrawingSurface* (JNICALL *GetDrawingSurface)
  263.     (JNIEnv* env, jobject target);
  264.     /*
  265.      * Free the drawing surface allocated in GetDrawingSurface.
  266.      */
  267.     void (JNICALL *FreeDrawingSurface)
  268.     (JAWT_DrawingSurface* ds);
  269. } JAWT;
  270.  
  271. /*
  272.  * Get the AWT native structure.  This function returns JNI_FALSE if
  273.  * an error occurs.
  274.  */
  275. _JNI_IMPORT_OR_EXPORT_
  276. jboolean JNICALL JAWT_GetAWT(JNIEnv* env, JAWT* awt);
  277.  
  278. #define JAWT_VERSION_1_3 0x00010003
  279.  
  280. #ifdef __cplusplus
  281. } /* extern "C" */
  282. #endif
  283.  
  284. #endif /* !_JAVASOFT_JAWT_H_ */
  285.