J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Copyright 1998-2001 Sun Microsystems, Inc. All Rights Reserved. |
| 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| 4 | * |
| 5 | * This code is free software; you can redistribute it and/or modify it |
| 6 | * under the terms of the GNU General Public License version 2 only, as |
| 7 | * published by the Free Software Foundation. Sun designates this |
| 8 | * particular file as subject to the "Classpath" exception as provided |
| 9 | * by Sun in the LICENSE file that accompanied this code. |
| 10 | * |
| 11 | * This code is distributed in the hope that it will be useful, but WITHOUT |
| 12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| 13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| 14 | * version 2 for more details (a copy is included in the LICENSE file that |
| 15 | * accompanied this code). |
| 16 | * |
| 17 | * You should have received a copy of the GNU General Public License version |
| 18 | * 2 along with this work; if not, write to the Free Software Foundation, |
| 19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| 20 | * |
| 21 | * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 22 | * CA 95054 USA or visit www.sun.com if you need additional information or |
| 23 | * have any questions. |
| 24 | */ |
| 25 | |
| 26 | /* |
| 27 | * The JDGA interface enables "Direct Graphics Access" to the pixels |
| 28 | * of X11 drawables for the Java runtime graphics implementation. |
| 29 | * |
| 30 | * This include file defines the external interface that the |
| 31 | * Solaris X11 port of the Java(tm) 2D API uses to communicate |
| 32 | * with a dynamically loadable object library to obtain information |
| 33 | * for rendering directly to the memory mapped surfaces that store |
| 34 | * the pixel information for an X11 Window (or technically any X11 |
| 35 | * Drawable). |
| 36 | * |
| 37 | * The 2D graphics library will link to an object file, either |
| 38 | * through direct linking at compile time or through dynamic |
| 39 | * loading at runtime, and use an entry point defined as |
| 40 | * |
| 41 | * JDgaLibInitFunc JDgaLibInit; |
| 42 | * |
| 43 | * to initialize the library and obtain a copy of a JDgaLibInfo |
| 44 | * structure that will be used to communicate with the library |
| 45 | * to obtain information about X11 Drawable IDs and the memory |
| 46 | * used to store their pixels. |
| 47 | * |
| 48 | * Some parts of this interface use interfaces and structures |
| 49 | * defined by the JNI native interface technology. |
| 50 | */ |
| 51 | |
| 52 | #ifndef HEADLESS |
| 53 | /* |
| 54 | * |
| 55 | */ |
| 56 | #define JDGALIB_MAJOR_VERSION 1 |
| 57 | #define JDGALIB_MINOR_VERSION 0 |
| 58 | |
| 59 | /* |
| 60 | * Definitions for the return status codes for most of the JDGA |
| 61 | * access functions. |
| 62 | */ |
| 63 | #ifndef _DEFINE_JDGASTATUS_ |
| 64 | #define _DEFINE_JDGASTATUS_ |
| 65 | typedef enum { |
| 66 | JDGA_SUCCESS = 0, /* operation succeeded */ |
| 67 | JDGA_FAILED = 1, /* unable to complete operation */ |
| 68 | JDGA_UNAVAILABLE = 2 /* DGA not available on attached devices */ |
| 69 | } JDgaStatus; |
| 70 | #endif |
| 71 | |
| 72 | /* |
| 73 | * This structure defines the location and size of a rectangular |
| 74 | * region of a drawing surface. |
| 75 | * |
| 76 | * lox, loy - coordinates that point to the pixel just inside |
| 77 | * the top left-hand corner of the region. |
| 78 | * hix, hiy - coordinates that point to the pixel just beyond |
| 79 | * the bottom right-hand corner of the region. |
| 80 | * |
| 81 | * Thus, the region is a rectangle containing (hiy-loy) rows of |
| 82 | * (hix-lox) columns of pixels. |
| 83 | */ |
| 84 | typedef struct { |
| 85 | jint lox; |
| 86 | jint loy; |
| 87 | jint hix; |
| 88 | jint hiy; |
| 89 | } JDgaBounds; |
| 90 | |
| 91 | typedef struct { |
| 92 | /* |
| 93 | * Information describing the global memory partition containing |
| 94 | * the pixel information for the window. |
| 95 | */ |
| 96 | void *basePtr; /* Base address of memory partition. */ |
| 97 | jint surfaceScan; /* Number of pixels from one row to the next */ |
| 98 | jint surfaceWidth; /* Total accessible pixels across */ |
| 99 | jint surfaceHeight; /* Total accessible pixels down */ |
| 100 | jint surfaceDepth; /* Mapped depth */ |
| 101 | |
| 102 | /* |
| 103 | * Location and size information of the entire window (may include |
| 104 | * portions outside of the memory partition). |
| 105 | * |
| 106 | * The coordinates are relative to the "basePtr" origin of the screen. |
| 107 | */ |
| 108 | JDgaBounds window; |
| 109 | |
| 110 | /* |
| 111 | * Location and size information of the visible portion of the |
| 112 | * window (includes only portions that are inside the writable |
| 113 | * portion of the memory partition and not covered by other windows) |
| 114 | * |
| 115 | * This rectangle may represent a subset of the rendering |
| 116 | * rectangle supplied in the JDgaGetLock function if that |
| 117 | * rectangle is partially clipped and the remaining visible |
| 118 | * portion is exactly rectangular. |
| 119 | * |
| 120 | * The coordinates are relative to the "basePtr" origin of the screen. |
| 121 | */ |
| 122 | JDgaBounds visible; |
| 123 | |
| 124 | } JDgaSurfaceInfo; |
| 125 | |
| 126 | typedef struct _JDgaLibInfo JDgaLibInfo; |
| 127 | |
| 128 | /* |
| 129 | * This function is called to initialize the JDGA implementation |
| 130 | * library for access to the given X11 Display. |
| 131 | * This function stores a pointer to a structure that holds function |
| 132 | * pointers for the rest of the requests as well as any additinoal |
| 133 | * data that that library needs to track the indicated display. |
| 134 | * |
| 135 | * @return |
| 136 | * JDGA_SUCCESS if library was successfully initialized |
| 137 | * JDGA_FAILED if library is unable to perform operations |
| 138 | * on the given X11 Display. |
| 139 | */ |
| 140 | typedef JDgaStatus |
| 141 | JDgaLibInitFunc(JNIEnv *env, JDgaLibInfo *ppInfo); |
| 142 | |
| 143 | /* |
| 144 | * This function is called to lock the given X11 Drawable into |
| 145 | * a locally addressable memory location and to return specific |
| 146 | * rendering information about the location and geometry of the |
| 147 | * display memory that the Drawable occupies. |
| 148 | * |
| 149 | * Information provided to this function includes: |
| 150 | * |
| 151 | * lox, loy - the X and Y coordinates of the pixel just inside |
| 152 | * the upper left corner of the region to be rendered |
| 153 | * hix, hiy - the X and Y coordinates of the pixel just beyond |
| 154 | * the lower right corner of the region to be rendered |
| 155 | * |
| 156 | * Information obtained via this function includes: |
| 157 | * |
| 158 | * *pSurface - A pointer to a JDgaSurfaceInfo structure which is |
| 159 | * filled in with information about the drawing area for |
| 160 | * the specified Drawable. |
| 161 | * |
| 162 | * The return value indicates whether or not the library was able |
| 163 | * to successfully lock the drawable into memory and obtain the |
| 164 | * specific geometry information required to render to the Drawable's |
| 165 | * pixel memory. Failure indicates only a temporary inability to |
| 166 | * lock down the memory for this Drawable and does not imply a general |
| 167 | * inability to lock this or other Drawable's at a later time. |
| 168 | * |
| 169 | * If the indicated rendering region is not visible at all then this |
| 170 | * function should indicate JDGA_SUCCESS and return an empty |
| 171 | * "visible" rectangle. |
| 172 | * If the indicated rendering region has a visible portion that cannot |
| 173 | * be expressed as a single rectangle in the JDgaSurfaceInfo structure |
| 174 | * then JDGA_FAILED should be indicated so that the rendering library |
| 175 | * can back off to another rendering mechanism. |
| 176 | * |
| 177 | * @return |
| 178 | * JDGA_SUCCESS memory successfully locked and described |
| 179 | * JDGA_FAILED temporary failure to lock the specified Drawable |
| 180 | */ |
| 181 | typedef JDgaStatus |
| 182 | JDgaGetLockFunc(JNIEnv *env, Display *display, void **dgaDev, |
| 183 | Drawable d, JDgaSurfaceInfo *pSurface, |
| 184 | jint lox, jint loy, jint hix, jint hiy); |
| 185 | |
| 186 | /* |
| 187 | * This function is called to unlock the locally addressable memory |
| 188 | * associated with the given X11 Drawable until the next rendering |
| 189 | * operation. The JDgaSurfaceInfo structure supplied is the same |
| 190 | * structure that was supplied in the dga_get_lock function and |
| 191 | * can be used to determine implementation specific data needed to |
| 192 | * manage the access lock for the indicated drawable. |
| 193 | * |
| 194 | * The return value indicates whether or not the library was able |
| 195 | * to successfully remove its lock. Typically failure indicates |
| 196 | * only that the lock had been invalidated through external means |
| 197 | * before the rendering library completed its work and is for |
| 198 | * informational purposes only, though it could also mean that |
| 199 | * the rendering library asked to unlock a Drawable that it had |
| 200 | * never locked. |
| 201 | * |
| 202 | * @return |
| 203 | * JDGA_SUCCESS lock successfully released |
| 204 | * JDGA_FAILED unable to release lock for some reason, |
| 205 | * typically the lock was already invalid |
| 206 | */ |
| 207 | typedef JDgaStatus |
| 208 | JDgaReleaseLockFunc(JNIEnv *env, void *dgaDev, Drawable d); |
| 209 | |
| 210 | /* |
| 211 | * This function is called to inform the JDGA library that the |
| 212 | * AWT rendering library has enqueued an X11 request for the |
| 213 | * indicated Drawable. The JDGA library will have to synchronize |
| 214 | * the X11 output buffer with the server before this drawable |
| 215 | * is again locked in order to prevent race conditions between |
| 216 | * the rendering operations in the X11 queue and the rendering |
| 217 | * operations performed directly between calls to the GetLockFunc |
| 218 | * and the ReleaseLockFunc. |
| 219 | */ |
| 220 | typedef void |
| 221 | JDgaXRequestSentFunc(JNIEnv *env, void *dgaDev, Drawable d); |
| 222 | |
| 223 | /* |
| 224 | * This function is called to shut down a JDGA library implementation |
| 225 | * and dispose of any resources that it is using for a given display. |
| 226 | * |
| 227 | */ |
| 228 | |
| 229 | typedef void |
| 230 | JDgaLibDisposeFunc(JNIEnv *env); |
| 231 | |
| 232 | struct _JDgaLibInfo { |
| 233 | /* |
| 234 | * The X11 display structure that this instance of JDgaLibInfo |
| 235 | * structure is tracking. |
| 236 | */ |
| 237 | Display *display; |
| 238 | |
| 239 | /* |
| 240 | * Pointers to the utility functions to query information about |
| 241 | * X11 drawables and perform synchronization on them. |
| 242 | */ |
| 243 | JDgaGetLockFunc *pGetLock; |
| 244 | JDgaReleaseLockFunc *pReleaseLock; |
| 245 | JDgaXRequestSentFunc *pXRequestSent; |
| 246 | JDgaLibDisposeFunc *pLibDispose; |
| 247 | |
| 248 | /* |
| 249 | * Since the JDGA library is responsible for allocating this |
| 250 | * structure, implementation specific information can be tracked |
| 251 | * by the library by declaring its own structure that contains |
| 252 | * data following the above members. |
| 253 | */ |
| 254 | }; |
| 255 | #endif /* !HEADLESS */ |