1 /*
   2  * Copyright (c) 1999, 2007, 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  * This include file contains information on how to use a SurfaceData
  28  * object from native code.
  29  */
  30 
  31 #ifndef _Included_SurfaceData
  32 #define _Included_SurfaceData
  33 
  34 #include <jni.h>
  35 
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39 
  40 /*
  41  * This structure is used to represent a rectangular bounding box
  42  * throughout various functions in the native SurfaceData API.
  43  *
  44  * All coordinates (x1 <= x < x2, y1 <= y < y2) are considered to
  45  * be inside these bounds.
  46  */
  47 typedef struct {
  48     jint x1;
  49     jint y1;
  50     jint x2;
  51     jint y2;
  52 } SurfaceDataBounds;
  53 
  54 #define SD_RASINFO_PRIVATE_SIZE         64
  55 
  56 /*
  57  * The SurfaceDataRasInfo structure is used to pass in and return various
  58  * pieces of information about the destination drawable.  In particular:
  59  *
  60  *      SurfaceDataBounds bounds;
  61  * [Needed for SD_LOCK_READ or SD_LOCK_WRITE]
  62  * The 2 dimensional bounds of the raster array that is needed.  Valid
  63  * memory locations are required at:
  64  *      *(pixeltype *) (((char *)rasBase) + y * scanStride + x * pixelStride)
  65  * for each x, y pair such that (bounds.x1 <= x < bounds.x2) and
  66  * (bounds.y1 <= y < bounds.y2).
  67  *
  68  *      void *rasBase;
  69  * [Requires SD_LOCK_READ or SD_LOCK_WRITE]
  70  * A pointer to the device space origin (0, 0) of the indicated raster
  71  * data.  This pointer may point to a location that is outside of the
  72  * allocated memory for the requested bounds and it may even point
  73  * outside of accessible memory.  Only the locations that fall within
  74  * the coordinates indicated by the requested bounds are guaranteed
  75  * to be accessible.
  76  *
  77  *      jint pixelBitOffset;
  78  * [Requires SD_LOCK_READ or SD_LOCK_WRITE]
  79  * The number of bits offset from the beginning of the first byte
  80  * of a scanline to the first bit of the first pixel on that scanline.
  81  * The bit offset must be less than 8 and it must be the same for each
  82  * scanline.  This field is only needed by image types which pack
  83  * multiple pixels into a byte, such as ByteBinary1Bit et al.  For
  84  * image types which use whole bytes (or shorts or ints) to store
  85  * their pixels, this field will always be 0.
  86  *
  87  *      jint pixelStride;
  88  * [Requires SD_LOCK_READ or SD_LOCK_WRITE]
  89  * The pixel stride is the distance in bytes from the data for one pixel
  90  * to the data for the pixel at the next x coordinate (x, y) => (x+1, y).
  91  * For data types that pack multiple pixels into a byte, such as
  92  * ByteBinary1Bit et al, this field will be 0 and the loops which
  93  * render to and from such data need to calculate their own offset
  94  * from the beginning of the scanline using the absolute x coordinate
  95  * combined with the pixelBitOffset field.
  96  * Bugfix 6220829 - this field used to be unsigned int, but some
  97  * primitives used negative pixel offsets and the corresponding
  98  * unsigned stride values caused the resulting pixel offset to
  99  * to always be a positive 32-bit quantity - causing problems on
 100  * 64-bit architectures.
 101  *
 102  *      jint scanStride;
 103  * [Requires SD_LOCK_READ or SD_LOCK_WRITE]
 104  * The scan stride is the distance in bytes from the data for one pixel
 105  * to the data for the pixel at the next y coordinate (x, y) => (x, y+1).
 106  * Bugfix 6220829 - this field used to be unsigned int, but some
 107  * primitives used negative pixel offsets and the corresponding
 108  * unsigned stride values caused the resulting pixel offset to
 109  * to always be a positive 32-bit quantity - causing problems on
 110  * 64-bit architectures.
 111  *
 112  *      unsigned int lutSize;
 113  * [Requires SD_LOCK_LUT]
 114  * The number of entries in the color lookup table.  The data beyond the
 115  * end of the map will be undefined.
 116  *
 117  *      jint *lutBase;
 118  * [Requires SD_LOCK_LUT]
 119  * A pointer to the beginning of the color lookup table for the colormap.
 120  * The color lookup table is formatted as an array of jint values each
 121  * representing the 32-bit ARGB color for the pixel representing by the
 122  * corresponding index.  The table is guaranteed to contain at least 256
 123  * valid memory locations even if the size of the map is smaller than 256.
 124  *
 125  *      unsigned char *invColorTable;
 126  * [Requires SD_LOCK_INVCOLOR]
 127  * A pointer to the beginning of the inverse color lookup table for the
 128  * colormap.  The inverse color lookup table is formatted as a 32x32x32
 129  * array of bytes indexed by RxGxB where each component is reduced to 5
 130  * bits of precision before indexing.
 131  *
 132  *      char *redErrTable;
 133  *      char *grnErrTable;
 134  *      char *bluErrTable;
 135  * [Requires SD_LOCK_INVCOLOR]
 136  * Pointers to the beginning of the ordered dither color error tables
 137  * for the colormap.  The error tables are formatted as an 8x8 array
 138  * of bytes indexed by coordinates using the formula [y & 7][x & 7].
 139  *
 140  *      int *invGrayTable;
 141  * [Requires SD_LOCK_INVGRAY]
 142  * A pointer to the beginning of the inverse gray lookup table for the
 143  * colormap.  The inverse color lookup table is formatted as an array
 144  * of 256 integers indexed by a byte gray level and storing an index
 145  * into the colormap of the closest matching gray pixel.
 146  *
 147  *      union priv {};
 148  * A buffer of private data for the SurfaceData implementation.
 149  * This field is a union of a data block of the desired default
 150  * size (SD_RASINFO_PRIVATE_SIZE) and a (void *) pointer that
 151  * ensures proper "strictest" alignment on all platforms.
 152  */
 153 typedef struct {
 154     SurfaceDataBounds   bounds;                 /* bounds of raster array */
 155     void                *rasBase;               /* Pointer to (0, 0) pixel */
 156     jint                pixelBitOffset;         /* bit offset to (0, *) pixel */
 157     jint                pixelStride;            /* bytes to next X pixel */
 158     jint                scanStride;             /* bytes to next Y pixel */
 159     unsigned int        lutSize;                /* # colors in colormap */
 160     jint                *lutBase;               /* Pointer to colormap[0] */
 161     unsigned char       *invColorTable;         /* Inverse color table */
 162     char                *redErrTable;           /* Red ordered dither table */
 163     char                *grnErrTable;           /* Green ordered dither table */
 164     char                *bluErrTable;           /* Blue ordered dither table */
 165     int                 *invGrayTable;          /* Inverse gray table */
 166     int                 representsPrimaries;    /* whether cmap represents primary colors */
 167     union {
 168         void            *align;                 /* ensures strict alignment */
 169         char            data[SD_RASINFO_PRIVATE_SIZE];
 170     } priv;
 171 } SurfaceDataRasInfo;
 172 
 173 typedef struct _SurfaceDataOps SurfaceDataOps;
 174 
 175 /*
 176  * This function is used to lock a particular region of a particular
 177  * destination.  Once this method is called, no changes of any of the
 178  * data returned by any of the other SurfaceData vectored functions
 179  * may change until a corresponding call to Release is made.
 180  *
 181  * The env parameter should be the JNIEnv of the surrounding JNI context.
 182  *
 183  * The ops parameter should be a pointer to the ops object upon which
 184  * this function is being invoked.
 185  *
 186  * The rasInfo parameter should be a pointer to a SurfaceDataRasInfo
 187  * structure in which the bounds have been initialized to the maximum
 188  * bounds of the raster data that will need to be accessed later.
 189  *
 190  * The lockflags parameter should indicate which information will be
 191  * needed by the caller.  The various flags which may be OR'd together
 192  * may consist of any of the following:
 193  *      SD_LOCK_READ            The caller needs to read pixels from the dest
 194  *      SD_LOCK_WRITE           The caller needs to write pixels to the dest
 195  *      SD_LOCK_RD_WR           A combination of (SD_LOCK_READ | SD_LOCK_WRITE)
 196  *      SD_LOCK_LUT             The caller needs the colormap (Lut)
 197  *      SD_LOCK_INVCOLOR        The caller needs the inverse color table
 198  *      SD_LOCK_INVGRAY         The caller needs the inverse gray table
 199  *      SD_LOCK_FASTEST         The caller only wants direct pixel access
 200  * Note that the SD_LOCK_LUT, SD_LOCK_INVCOLOR, and SD_LOCK_INVGRAY flags
 201  * are only valid for destinations with IndexColorModels.
 202  * Also note that SD_LOCK_FASTEST will only succeed if the access to the
 203  * pixels will occur just as fast regardless of the size of the bounds.
 204  * This flag is used by the Text rendering routines to determine if it
 205  * matters whether or not they have calculated a tight bounding box for
 206  * the pixels they will be touching.
 207  *
 208  * Return value:
 209  *
 210  * If this function succeeds, it will return SD_SUCCESS (0).
 211  *
 212  * If this function is unable to honor the SD_LOCK_FASTEST flag,
 213  * it will return SD_SLOWLOCK.  The bounds parameter of the
 214  * SurfaceDataRasInfo object should be intersected with a tighter
 215  * bounding rectangle before calling the GetRasInfo function so
 216  * as to minimize the amount pixel copying or conversion.  Note
 217  * that the Lock function may have already intersected the
 218  * bounds with a tighter rectangle as it tried to honor the
 219  * SD_SLOWLOCK flag and so the caller should only use intersection
 220  * operations to further restrict the bounds.
 221  *
 222  * If this function fails for any reason that is not recoverable,
 223  * it will throw an appropriate Java exception and return SD_FAILED.
 224  *
 225  * Operation:
 226  *
 227  * This function will intersect the bounds specified in the rasInfo
 228  * parameter with the available raster data in the destination drawable
 229  * and modify the contents of the bounds field to represent the maximum
 230  * available raster data.
 231  *
 232  * If the available raster data in the destination drawable consists of
 233  * a non-rectangular region of pixels, this method may throw an InvalidPipe
 234  * exception (optionally the object may decide to provide a copy of the
 235  * destination pixel data with undefined data in the inaccessible portions).
 236  *
 237  * Further processing by the caller may discover that a smaller region of
 238  * data is actually needed and the call to GetRasData can be made with a
 239  * still smaller bounds.
 240  *
 241  * Note to callers:
 242  *      This function may use JNI methods so it is important that the
 243  *      caller not have any outstanding GetPrimitiveArrayCritical or
 244  *      GetStringCritical locks which have not been released.
 245  *
 246  * Note to implementers:
 247  *      The caller may also continue to use JNI methods after this method
 248  *      is called so it is important that implementations of SurfaceData
 249  *      not return from this function with any outstanding JNI Critical
 250  *      locks that have not been released.
 251  */
 252 typedef jint LockFunc(JNIEnv *env,
 253                       SurfaceDataOps *ops,
 254                       SurfaceDataRasInfo *rasInfo,
 255                       jint lockflags);
 256 
 257 /*
 258  * This function returns information about the raster data for the drawable.
 259  * The function will fill in or modify the contents of the SurfaceDataRasInfo
 260  * structure that is passed in with various pieces of information depending
 261  * on what was requested in the lockflags parameter that was handed into
 262  * the LockFunc.  For more information on which pieces of information are
 263  * returned based upon the lock flags see the documentation for the
 264  * RasInfo structure above.
 265  *
 266  * The env parameter should be the JNIEnv of the surrounding JNI context.
 267  *
 268  * The ops parameter should be a pointer to the ops object upon which
 269  * this function is being invoked.
 270  *
 271  * The pRasInfo parameter should be a pointer to the same structure of type
 272  * SurfaceDataRasInfo.  The bounds member of that structure should be
 273  * initialized to the bounding box of the raster data that is actually
 274  * needed for reading or writing before calling this function.  These
 275  * bounds must be a subset of the raster bounds that were given to the
 276  * LockFunc or the results will be undefined.
 277  *
 278  * If the surface was locked with the flag SD_LOCK_FASTEST then this
 279  * function may reevaluate the bounds in the RasInfo structure and
 280  * return a subset of what was requested.  Callers that use that flag
 281  * should be prepared to reevaluate their clipping after GetRasInfo
 282  * returns.  If the SD_LOCK_FASTEST flag was not specified, then this
 283  * function will return a buffer containing all of the pixels in the
 284  * requested bounds without reevaluating them.
 285  *
 286  * Any information that was requested in the lockflags of the LockFunc
 287  * will be returned and NULL pointers will be returned for all other
 288  * information.
 289  *
 290  * Note to callers:
 291  *      This function may use JNI Critical methods so it is important
 292  *      that the caller not call any other JNI methods after this function
 293  *      returns until the Release function is called.
 294  */
 295 typedef void GetRasInfoFunc(JNIEnv *env,
 296                             SurfaceDataOps *ops,
 297                             SurfaceDataRasInfo *pRasInfo);
 298 
 299 /*
 300  * This function releases all of the Critical data for the specified
 301  * drawable.
 302  *
 303  * This function vector is allowed to be NULL if a given SurfaceData
 304  * implementation does not require the use of JNI Critical array locks.
 305  * Callers should use the "SurfaceData_InvokeRelease(env, ops)" macro
 306  * to handle the conditional invocation of this function.
 307  *
 308  * In particular, this function will release any outstanding JNI Critical
 309  * locks that the SurfaceData implementation may have used so that it
 310  * will be safe for the caller to start using arbitrary JNI calls or
 311  * return from its calling JNI function.
 312  *
 313  * The env parameter should be the JNIEnv of the surrounding JNI context.
 314  *
 315  * The ops parameter should be a pointer to the ops object upon which
 316  * this function is being invoked.
 317  *
 318  * The pRasInfo parameter should be a pointer to the same structure of
 319  * type SurfaceDataRasInfo that was passed to the GetRasInfo function.
 320  * The bounds should be unchanged since that call.
 321  *
 322  * Note to callers:
 323  *      This function will release any outstanding JNI Critical locks so
 324  *      it will once again be safe to use arbitrary JNI calls or return
 325  *      to the enclosing JNI native context.
 326  *
 327  * Note to implementers:
 328  *      This function may not use any JNI methods other than to release
 329  *      outstanding JNI Critical array locks since there may be other
 330  *      nested SurfacData objects holding locks with their own outstanding
 331  *      JNI Critical locks.  This restriction includes the use of the
 332  *      JNI monitor calls so that all MonitorExit invocations must be
 333  *      done in the Unlock function.
 334  */
 335 typedef void ReleaseFunc(JNIEnv *env,
 336                          SurfaceDataOps *ops,
 337                          SurfaceDataRasInfo *pRasInfo);
 338 
 339 /*
 340  * This function unlocks the specified drawable.
 341  *
 342  * This function vector is allowed to be NULL if a given SurfaceData
 343  * implementation does not require any unlocking of the destination.
 344  * Callers should use the "SurfaceData_InvokeUnlock(env, ops)" macro
 345  * to handle the conditional invocation of this function.
 346  *
 347  * The env parameter should be the JNIEnv of the surrounding JNI context.
 348  *
 349  * The ops parameter should be a pointer to the ops object upon which
 350  * this function is being invoked.
 351  *
 352  * The pRasInfo parameter should be a pointer to the same structure of
 353  * type SurfaceDataRasInfo that was passed to the GetRasInfo function.
 354  * The bounds should be unchanged since that call.
 355  *
 356  * Note to callers:
 357  *      This function may use JNI methods so it is important that the
 358  *      caller not have any outstanding GetPrimitiveArrayCritical or
 359  *      GetStringCritical locks which have not been released.
 360  *
 361  * Note to implementers:
 362  *      This function may be used to release any JNI monitors used to
 363  *      prevent the destination from being modified.  It may also be
 364  *      used to perform operations which may require blocking (such as
 365  *      executing X11 operations which may need to flush data).
 366  */
 367 typedef void UnlockFunc(JNIEnv *env,
 368                         SurfaceDataOps *ops,
 369                         SurfaceDataRasInfo *pRasInfo);
 370 
 371 /*
 372  * This function sets up the specified drawable.  Some surfaces may
 373  * need to perform certain operations during Setup that cannot be
 374  * done after later operations such as Lock.  For example, on
 375  * win9x systems, when any surface is locked we cannot make a call to
 376  * the message-handling thread.
 377  *
 378  * This function vector is allowed to be NULL if a given SurfaceData
 379  * implementation does not require any setup.
 380  *
 381  * The env parameter should be the JNIEnv of the surrounding JNI context.
 382  *
 383  * The ops parameter should be a pointer to the ops object upon which
 384  * this function is being invoked.
 385  *
 386  * Note to callers:
 387  *      This function may use JNI methods so it is important that the
 388  *      caller not have any outstanding GetPrimitiveArrayCritical or
 389  *      GetStringCritical locks which have not been released.
 390  */
 391 typedef void SetupFunc(JNIEnv *env,
 392                        SurfaceDataOps *ops);
 393 
 394 /*
 395  * This function disposes the specified SurfaceDataOps structure
 396  * and associated native resources.
 397  * The implementation is SurfaceData-type specific.
 398  */
 399 typedef void DisposeFunc(JNIEnv *env,
 400                          SurfaceDataOps *ops);
 401 
 402 /*
 403  * Constants used for return values.  Constants less than 0 are
 404  * unrecoverable failures and indicate that a Java exception has
 405  * already been thrown.  Constants greater than 0 are conditional
 406  * successes which warn the caller that various optional features
 407  * were not available so that workarounds can be used.
 408  */
 409 #define SD_FAILURE              -1
 410 #define SD_SUCCESS              0
 411 #define SD_SLOWLOCK             1
 412 
 413 /*
 414  * Constants for the flags used in the Lock function.
 415  */
 416 #define SD_LOCK_READ            (1 << 0)
 417 #define SD_LOCK_WRITE           (1 << 1)
 418 #define SD_LOCK_RD_WR           (SD_LOCK_READ | SD_LOCK_WRITE)
 419 #define SD_LOCK_LUT             (1 << 2)
 420 #define SD_LOCK_INVCOLOR        (1 << 3)
 421 #define SD_LOCK_INVGRAY         (1 << 4)
 422 #define SD_LOCK_FASTEST         (1 << 5)
 423 #define SD_LOCK_PARTIAL         (1 << 6)
 424 #define SD_LOCK_PARTIAL_WRITE   (SD_LOCK_WRITE | SD_LOCK_PARTIAL)
 425 #define SD_LOCK_NEED_PIXELS     (SD_LOCK_READ | SD_LOCK_PARTIAL)
 426 
 427 /*
 428  * This structure provides the function vectors for manipulating
 429  * and retrieving information about the destination drawable.
 430  * There are also variables for the surface data object used by
 431  * native code to track the state of the surface.
 432  * The sdObject is a pointer to the Java SurfaceData object;
 433  * this is set in SurfaceData_InitOps() and used by any object
 434  * using the ops structure to refer to elements in the Java object
 435  * (such as fields that we need to set from native code).
 436  */
 437 struct _SurfaceDataOps {
 438     LockFunc            *Lock;
 439     GetRasInfoFunc      *GetRasInfo;
 440     ReleaseFunc         *Release;
 441     UnlockFunc          *Unlock;
 442     SetupFunc           *Setup;
 443     DisposeFunc         *Dispose;
 444     jobject             sdObject;
 445 };
 446 
 447 #define _ClrReduce(c)   (((unsigned char) c) >> 3)
 448 
 449 /*
 450  * This macro performs a lookup in an inverse color table given 3 8-bit
 451  * RGB primaries.  It automates the process of reducing the primaries
 452  * to 5-bits of precision and using them to index into the specified
 453  * inverse color lookup table.
 454  */
 455 #define SurfaceData_InvColorMap(invcolortbl, r, g, b) \
 456     (invcolortbl)[(_ClrReduce(r)<<10) + (_ClrReduce(g)<<5) + _ClrReduce(b)]
 457 
 458 /*
 459  * This macro invokes the SurfaceData Release function only if the
 460  * function vector is not NULL.
 461  */
 462 #define SurfaceData_InvokeRelease(env, ops, pRI)        \
 463     do {                                                \
 464         if ((ops)->Release != NULL) {                   \
 465             (ops)->Release(env, ops, pRI);              \
 466         }                                               \
 467     } while(0)
 468 
 469 /*
 470  * This macro invokes the SurfaceData Unlock function only if the
 471  * function vector is not NULL.
 472  */
 473 #define SurfaceData_InvokeUnlock(env, ops, pRI)         \
 474     do {                                                \
 475         if ((ops)->Unlock != NULL) {                    \
 476             (ops)->Unlock(env, ops, pRI);               \
 477         }                                               \
 478     } while(0)
 479 
 480 /*
 481  * This macro invokes both the SurfaceData Release and Unlock functions
 482  * only if the function vectors are not NULL.  It can be used in cases
 483  * where only one surface has been accessed and where no other JNI
 484  * Critical locks (which would need to be released after Release and
 485  * before Unlock) are held by the calling function.
 486  */
 487 #define SurfaceData_InvokeReleaseUnlock(env, ops, pRI)  \
 488     do {                                                \
 489         if ((ops)->Release != NULL) {                   \
 490             (ops)->Release(env, ops, pRI);              \
 491         }                                               \
 492         if ((ops)->Unlock != NULL) {                    \
 493             (ops)->Unlock(env, ops, pRI);               \
 494         }                                               \
 495     } while(0)
 496 
 497 /*
 498  * This macro invokes both the SurfaceData Release and Unlock functions
 499  * on two nested drawables only if the function vectors are not NULL.
 500  * It can be used in cases where two surfaces have been accessed and
 501  * where no other JNI Critical locks (which would need to be released
 502  * after Release and before Unlock) are held by the calling function.  The
 503  * two ops vectors should be specified in the same order that they were
 504  * locked.  Both surfaces will be released and then both unlocked.
 505  */
 506 #define SurfaceData_InvokeReleaseUnlock2(env, ops1, pRI1, ops2, pRI2)   \
 507     do {                                                        \
 508         if ((ops2)->Release != NULL) {                          \
 509             (ops2)->Release(env, ops2, pRI2);                   \
 510         }                                                       \
 511         if ((ops1)->Release != NULL) {                          \
 512             (ops1)->Release(env, ops1, pRI1);                   \
 513         }                                                       \
 514         if ((ops2)->Unlock != NULL) {                           \
 515             (ops2)->Unlock(env, ops2, pRI2);                    \
 516         }                                                       \
 517         if ((ops1)->Unlock != NULL) {                           \
 518             (ops1)->Unlock(env, ops1, pRI1);                    \
 519         }                                                       \
 520     } while(0)
 521 
 522 #define SurfaceData_InvokeDispose(env, ops)                     \
 523     do {                                                        \
 524         if ((ops)->Dispose != NULL) {                           \
 525             (ops)->Dispose(env, ops);                           \
 526         }                                                       \
 527     } while(0)
 528 
 529 #define SurfaceData_InvokeSetup(env, ops)                       \
 530     do {                                                        \
 531         if ((ops)->Setup != NULL) {                             \
 532             (ops)->Setup(env, ops);                             \
 533         }                                                       \
 534     } while(0)
 535 
 536 /*
 537  * This function returns a pointer to a native SurfaceDataOps
 538  * structure for accessing the indicated SurfaceData Java object.
 539  *
 540  * Note to callers:
 541  *      This function uses JNI methods so it is important that the
 542  *      caller not have any outstanding GetPrimitiveArrayCritical or
 543  *      GetStringCritical locks which have not been released.
 544  *
 545  *      The caller may continue to use JNI methods after this method
 546  *      is called since this function will not leave any outstanding
 547  *      JNI Critical locks unreleased.
 548  */
 549 JNIEXPORT SurfaceDataOps * JNICALL
 550 SurfaceData_GetOps(JNIEnv *env, jobject sData);
 551 
 552 /*
 553  * Does the same as the above, but doesn't call Setup function
 554  * even if it's set.
 555  */
 556 JNIEXPORT SurfaceDataOps * JNICALL
 557 SurfaceData_GetOpsNoSetup(JNIEnv *env, jobject sData);
 558 
 559 /*
 560  * This function stores a pointer to a native SurfaceDataOps
 561  * structure into the indicated Java SurfaceData object.
 562  *
 563  * Note to callers:
 564  *      This function uses JNI methods so it is important that the
 565  *      caller not have any outstanding GetPrimitiveArrayCritical or
 566  *      GetStringCritical locks which have not been released.
 567  *
 568  *      The caller may continue to use JNI methods after this method
 569  *      is called since this function will not leave any outstanding
 570  *      JNI Critical locks unreleased.
 571  */
 572 JNIEXPORT void JNICALL
 573 SurfaceData_SetOps(JNIEnv *env, jobject sData, SurfaceDataOps *ops);
 574 
 575 /*
 576  * This function throws an InvalidPipeException which will cause the
 577  * calling SunGraphics2D object to revalidate its pipelines and call
 578  * again.  This utility method should be called from the SurfaceData
 579  * native Lock routine when some attribute of the surface has changed
 580  * that requires pipeline revalidation, including:
 581  *
 582  *      The bit depth or pixel format of the surface.
 583  *      The surface (window) has been disposed.
 584  *      The device clip of the surface has been changed (resize, visibility, etc.)
 585  *
 586  * Note to callers:
 587  *      This function uses JNI methods so it is important that the
 588  *      caller not have any outstanding GetPrimitiveArrayCritical or
 589  *      GetStringCritical locks which have not been released.
 590  *
 591  *      The caller may continue to use JNI methods after this method
 592  *      is called since this function will not leave any outstanding
 593  *      JNI Critical locks unreleased.
 594  */
 595 JNIEXPORT void JNICALL
 596 SurfaceData_ThrowInvalidPipeException(JNIEnv *env, const char *msg);
 597 
 598 /*
 599  * This function intersects two bounds objects which exist in the same
 600  * coordinate space.  The contents of the first parameter (dst) are
 601  * modified to contain the intersection of the two bounds while the
 602  * contents of the second parameter (src) are untouched.
 603  */
 604 JNIEXPORT void JNICALL
 605 SurfaceData_IntersectBounds(SurfaceDataBounds *dst, SurfaceDataBounds *src);
 606 
 607 /*
 608  * This function intersects a bounds object with a rectangle specified
 609  * in lox, loy, hix, hiy format in the same coordinate space.  The
 610  * contents of the first parameter (bounds) are modified to contain
 611  * the intersection of the two rectangular regions.
 612  */
 613 JNIEXPORT void JNICALL
 614 SurfaceData_IntersectBoundsXYXY(SurfaceDataBounds *bounds,
 615                                 jint lox, jint loy, jint hix, jint hiy);
 616 
 617 /*
 618  * This function intersects a bounds object with a rectangle specified
 619  * in XYWH format in the same coordinate space.  The contents of the
 620  * first parameter (bounds) are modified to contain the intersection
 621  * of the two rectangular regions.
 622  */
 623 JNIEXPORT void JNICALL
 624 SurfaceData_IntersectBoundsXYWH(SurfaceDataBounds *bounds,
 625                                 jint x, jint y, jint w, jint h);
 626 
 627 /*
 628  * This function intersects two bounds objects which exist in different
 629  * coordinate spaces.  The coordinate spaces of the two objects are
 630  * related such that a given coordinate in the space of the A bounds
 631  * is related to the analogous coordinate in the space of the B bounds
 632  * by the formula: (AX + BXminusAX, AY + BYminusAY) == (BX, BY).
 633  * The contents of both bounds objects are modified to represent their
 634  * mutual intersection.
 635  */
 636 JNIEXPORT void JNICALL
 637 SurfaceData_IntersectBlitBounds(SurfaceDataBounds *Abounds,
 638                                 SurfaceDataBounds *Bbounds,
 639                                 jint BXminusAX, jint BYminusAY);
 640 
 641 
 642 /*
 643  * This function creates and initializes the ops structure.  The function
 644  * is called by "subclasses" of SurfaceData (e.g., BufImgSurfaceData)
 645  * which pass in the size of the structure to allocate (subclasses generally
 646  * need additional fields in the ops structure particular to their usage
 647  * of the structure).  The structure is allocated and initialized
 648  * and is stored in the SurfaceData java object for later retrieval.
 649  * Subclasses of SurfaceData should call this function instead of allocating
 650  * the memory directly.
 651  */
 652 SurfaceDataOps *SurfaceData_InitOps(JNIEnv *env, jobject sData, int opsSize);
 653 
 654 /*
 655  * This function invokes the ops-specific disposal function.
 656  * It is a part of the finalizers-free disposal mechanism.
 657  * (see Disposer and DefaultDisposerRecord classes for more information)
 658  * It also destroys the ops structure created in SurfaceData_InitOps.
 659  */
 660 void SurfaceData_DisposeOps(JNIEnv *env, jlong ops);
 661 
 662 #ifdef __cplusplus
 663 };
 664 #endif
 665 
 666 #endif