src/java.desktop/share/native/include/jawt.h

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -36,31 +36,35 @@
  * AWT native interface.
  *
  * The AWT native interface allows a native C or C++ application a means
  * by which to access native structures in AWT.  This is to facilitate moving
  * legacy C and C++ applications to Java and to target the needs of the
- * community who, at present, wish to do their own native rendering to canvases
- * for performance reasons.  Standard extensions such as Java3D also require a
- * means to access the underlying native data structures of AWT.
- *
- * There may be future extensions to this API depending on demand.
- *
- * A VM does not have to implement this API in order to pass the JCK.
- * It is recommended, however, that this API is implemented on VMs that support
- * standard extensions, such as Java3D.
+ * developers who need to do their own native rendering to canvases
+ * for performance or other reasons.
+ *
+ * Conversely it also provides mechanisms for an application which already
+ * has a native window to provide that to AWT for AWT rendering.
+ * 
+ * Since every platform may be different in its native data structures
+ * and APIs for windowing systems the application must necessarily
+ * provided per-platform source and compile and deliver per-platform
+ * native code  to use this API.
+ *
+ * These interfaces are not part of the Java SE specification and
+ * a VM is not required to implement this API. However it is strongly
+ * recommended that all implementations which support headful AWT 
+ * also support these interfaces.
  *
- * Since this is a native API, any program which uses it cannot be considered
- * 100% pure java.
  */
 
 /*
  * AWT Native Drawing Surface (JAWT_DrawingSurface).
  *
  * For each platform, there is a native drawing surface structure.  This
  * platform-specific structure can be found in jawt_md.h.  It is recommended
  * that additional platforms follow the same model.  It is also recommended
- * that VMs on Win32 and Solaris support the existing structures in jawt_md.h.
+ * that VMs on all platforms support the existing structures in jawt_md.h.
  *
  *******************
  * EXAMPLE OF USAGE:
  *******************
  *

@@ -96,12 +100,12 @@
  *     JAWT_DrawingSurfaceInfo* dsi;
  *     JAWT_Win32DrawingSurfaceInfo* dsi_win;
  *     jboolean result;
  *     jint lock;
  *
- *     // Get the AWT
- *     awt.version = JAWT_VERSION_1_3;
+ *     // Get the AWT. Request version 9 to access features in that release.
+ *     awt.version = JAWT_VERSION_9;
  *     result = JAWT_GetAWT(env, &awt);
  *     assert(result != JNI_FALSE);
  *
  *     // Get the drawing surface
  *     ds = awt.GetDrawingSurface(env, canvas);

@@ -152,11 +156,11 @@
  */
 typedef struct jawt_DrawingSurfaceInfo {
     /*
      * Pointer to the platform-specific information.  This can be safely
      * cast to a JAWT_Win32DrawingSurfaceInfo on Windows or a
-     * JAWT_X11DrawingSurfaceInfo on Solaris. On Mac OS X this is a
+     * JAWT_X11DrawingSurfaceInfo on Linux and Solaris. On Mac OS X this is a
      * pointer to a NSObject that conforms to the JAWT_SurfaceLayers
      * protocol. See jawt_md.h for details.
      */
     void* platformInfo;
     /* Cached pointer to the underlying drawing surface */

@@ -235,11 +239,12 @@
  * Structure for containing native AWT functions.
  */
 typedef struct jawt {
     /*
      * Version of this structure.  This must always be set before
-     * calling JAWT_GetAWT()
+     * calling JAWT_GetAWT(). It affects the functions returned.
+     * Must be one of the known pre-defined versions.
      */
     jint version;
     /*
      * Return a drawing surface from a target jobject.  This value
      * may be cached.

@@ -330,10 +335,17 @@
  * an error occurs.
  */
 _JNI_IMPORT_OR_EXPORT_
 jboolean JNICALL JAWT_GetAWT(JNIEnv* env, JAWT* awt);
 
+/*
+ * Specify one of these constants as the JAWT.version
+ * Specifying an earlier version will limit the available functions to
+ * those provided in that earlier version of JAWT.
+ * See the "Since" note on each API. Methods with no "Since"
+ * may be presumed to be present in JAWT_VERSION_1_3.
+ */
 #define JAWT_VERSION_1_3 0x00010003
 #define JAWT_VERSION_1_4 0x00010004
 #define JAWT_VERSION_1_7 0x00010007
 #define JAWT_VERSION_9 0x00090000