1 /* 2 * Copyright (c) 1998, 2000, 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 #ifndef _JDGADEVICE_H_ 27 #define _JDGADEVICE_H_ 28 29 /* 30 * Interface for Supporting DGA to Framebuffers under Java 31 * ------------------------------------------------------- 32 * 33 * This interface will allow third party (and Sun) framebuffers which 34 * support the Direct Graphics Access (DGA) interface to be accessed with 35 * DGA in Java applications. 36 * 37 * It coexists with the existing device-independent interfaces provided in 38 * libsunwjdga.so. 39 * 40 * Framebuffers desiring access to Java DGA must supply a dynamically 41 * loaded library named "libjdga<fbname>.so", where <fbname> is the name 42 * returned by the VIS_GETIDENTIFIER ioctl as defined in the Solaris 43 * VISUAL environment (visual_io(7i)). For example, the Java DGA library 44 * for Sun's cg6 framebuffer will be named libjdgaSUNWcg6.so. 45 * 46 * Because multiple instances of a framebuffer type may exist on a system, 47 * the device-dependent library must avoid the use of static or global 48 * variables for any framebuffer-related variables. In other words it 49 * must be reentrant. 50 * 51 * The device-independent function Solaris_JDga_LibInit() is called in the 52 * static initializer for X11Graphics.java. Solaris_JDga_LibInit() will be 53 * modified to seek out a device-dependent DGA library as follows. 54 * 55 * - DGA grab the DefaultRootWindow to get a Dga_drawable. 56 * 57 * - Use the Dga_drawable ID to get the device file descriptor 58 * fd = dga_win_devfd(dga_draw_id) 59 * 60 * - Use the VIS_GETIDENTIFIER ioctl to get the device name string. 61 * 62 * - Construct the library path name using the device name string. 63 * The device-dependent library must be located in a location specified 64 * in the LD_LIBRARY_PATH. 65 * 66 * - The device-dependent library will be dlopen'ed and then a dlsym will 67 * be performed for the function "SolarisJDgaDevOpen", which must 68 * be implemented by the device-dependent library writer. 69 * 70 * - The function SolarisJDgaDevOpen() will then be called with a 71 * pointer to a SolarisJDgaDevInfo structure. This structure will 72 * have its major and minor version numbers filled in with their 73 * current values by the device-independent calling code. The 74 * device-dependent library must examine these version numbers and 75 * act as follows: 76 * 77 * - In all cases, the device-dependent code should reset the 78 * supplied major and minor version numbers to those of the 79 * device-dependent library. 80 * 81 * - If the supplied major version number is not the same as that 82 * of the device library, the open must fail and return JDGA_FAILED. 83 * 84 * - If the supplied minor version number is less than or equal to 85 * the device minor version number, then backward compatibility 86 * is assumed and the open should return JDGA_SUCCESS. 87 * 88 * - If the supplied minor version number is greater than the 89 * device minor version number, the open should also return 90 * JDGA_SUCCESS. The returned device minor version number will 91 * indicate to the device-independent code what features are 92 * supported in the device library. 93 * 94 * - The function SolarisJDgaDevOpen() must also return a structure 95 * containing function pointers as given in the SolarisJDgaDevFunc 96 * structure below. The winlock and winunlock functions are 97 * required only if there is some device-specific locking to be done 98 * in addition to the DGA lock. If this is not required for the device 99 * these function pointers may be specified as NULL pointers. 100 * 101 */ 102 103 #include <dga/dga.h> 104 #include <unistd.h> /* ioctl */ 105 #include <stdlib.h> 106 #include <sys/mman.h> /* mmap */ 107 #include <sys/visual_io.h> 108 #include <X11/Xlib.h> 109 110 /* 111 * Status return codes 112 */ 113 #ifndef _DEFINE_JDGASTATUS_ 114 #define _DEFINE_JDGASTATUS_ 115 typedef enum { 116 JDGA_SUCCESS = 0, /* operation succeeded */ 117 JDGA_FAILED = 1 /* unable to complete operation */ 118 } JDgaStatus; 119 #endif 120 121 /* 122 * Structure to be filled in by device-dependent library's 123 * SolarisJDgaDevOpen() function 124 */ 125 typedef struct { 126 char * visidName; /* device name from ioctl */ 127 int majorVersion; 128 int minorVersion; 129 struct _SolarisJDgaDevFuncList* function; /* Device function pointers */ 130 } SolarisJDgaDevInfo; 131 132 /* 133 * Structure returned by device-dependent library for a window 134 */ 135 typedef struct { 136 SolarisJDgaDevInfo* devInfo; /* Supplied by caller */ 137 Dga_drawable dgaDraw; /* Supplied by caller */ 138 caddr_t mapAddr; /* FB mapping for this window */ 139 int mapDepth; /* Depth in bits */ 140 int mapWidth; /* Width in pixels */ 141 int mapHeight; /* Height in lines */ 142 int mapLineStride; /* Byte stride line-to-line */ 143 int mapPixelStride; /* Byte stride pixel-to-pixel */ 144 void* privateData; /* Handle for device-dependent library */ 145 } SolarisJDgaWinInfo; 146 147 typedef JDgaStatus (*SolarisJDgaDevFunction)(SolarisJDgaDevInfo*); 148 typedef JDgaStatus (*SolarisJDgaWinFunction)(SolarisJDgaWinInfo*); 149 150 /* 151 * Structure for device-dependent functions 152 */ 153 typedef struct _SolarisJDgaDevFuncList { 154 SolarisJDgaDevFunction devclose; 155 SolarisJDgaWinFunction winopen; 156 SolarisJDgaWinFunction winclose; 157 SolarisJDgaWinFunction winlock; 158 SolarisJDgaWinFunction winunlock; 159 } SolarisJDgaDevFuncList; 160 161 /* 162 * Function to be supplied by the device-dependent library implementor. 163 * It will accept a SolarisJDgaDevInfo structure with a filled-in 164 * major and minor version number and will return updated version 165 * numbers and the function pointers described below. 166 */ 167 typedef JDgaStatus SolarisJDgaDevOpenFunc(SolarisJDgaDevInfo* devInfo); 168 169 JDgaStatus SolarisJDgaDevOpen(SolarisJDgaDevInfo* devInfo); 170 171 /* 172 * Functions supplied by the device-dependent library. 173 * These function pointers will be returned to the 174 * device-independent code in the SolarisJDgaDevFunc structure. 175 */ 176 177 JDgaStatus (*winopen)(SolarisJDgaWinInfo* info); 178 179 /* 180 * Fills in window-specific information in the supplied SolarisJDgaWinInfo 181 * structure. Because multiple windows may be open concurrently, 182 * implementations should avoid the use of static structures. 183 */ 184 185 JDgaStatus (*winclose)(SolarisJDgaWinInfo* info); 186 187 /* 188 * Frees any resources allocated by the device-dependent library for 189 * this window. It may also perform an unmap if this is the last 190 * window using this particular memory map. Devices, such as the FFB, 191 * which support multiple depths, can have different device memory 192 * mappings for different depths. 193 */ 194 195 JDgaStatus (*winlock)(SolarisJDgaWinInfo* info); 196 197 /* 198 * Performs any device-specific locking needed for the framebuffer. 199 * In most cases it will be unnecessary. In those cases, the 200 * device-dependent library can supply NULL for this function pointer. 201 */ 202 203 JDgaStatus (*winunlock)(SolarisJDgaWinInfo* info); 204 205 /* 206 * Performs any device-specific unlocking needed for the framebuffer. 207 * In most cases it will be unnecessary. In those cases, the 208 * device-dependent library can supply NULL for this function pointer. 209 */ 210 211 JDgaStatus (*devclose)(SolarisJDgaDevInfo* info); 212 213 /* 214 * This function will be called at the last usage of the framebuffer 215 * device to allow the library to clean up any remaining resources. 216 */ 217 218 #endif /* _JDGADEVICE_H_ */ 219