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 */