1 /* 2 * Copyright (c) 1998, 2001, Oracle and/or its affiliates. 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. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * 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 */ 256