2362N/A * Copyright (c) 1999, 2007, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A * This include file contains information on how to use a SurfaceData 0N/A * object from native code. 0N/A * This structure is used to represent a rectangular bounding box 0N/A * throughout various functions in the native SurfaceData API. 0N/A * All coordinates (x1 <= x < x2, y1 <= y < y2) are considered to 0N/A * be inside these bounds. 0N/A * The SurfaceDataRasInfo structure is used to pass in and return various 0N/A * pieces of information about the destination drawable. In particular: 0N/A * SurfaceDataBounds bounds; 0N/A * [Needed for SD_LOCK_READ or SD_LOCK_WRITE] 0N/A * The 2 dimensional bounds of the raster array that is needed. Valid 0N/A * memory locations are required at: 0N/A * *(pixeltype *) (((char *)rasBase) + y * scanStride + x * pixelStride) 0N/A * for each x, y pair such that (bounds.x1 <= x < bounds.x2) and 0N/A * (bounds.y1 <= y < bounds.y2). 0N/A * [Requires SD_LOCK_READ or SD_LOCK_WRITE] 0N/A * A pointer to the device space origin (0, 0) of the indicated raster 0N/A * data. This pointer may point to a location that is outside of the 0N/A * allocated memory for the requested bounds and it may even point 0N/A * outside of accessible memory. Only the locations that fall within 0N/A * the coordinates indicated by the requested bounds are guaranteed 0N/A * jint pixelBitOffset; 0N/A * [Requires SD_LOCK_READ or SD_LOCK_WRITE] 0N/A * The number of bits offset from the beginning of the first byte 0N/A * of a scanline to the first bit of the first pixel on that scanline. 0N/A * The bit offset must be less than 8 and it must be the same for each 0N/A * scanline. This field is only needed by image types which pack 0N/A * multiple pixels into a byte, such as ByteBinary1Bit et al. For 0N/A * image types which use whole bytes (or shorts or ints) to store 0N/A * their pixels, this field will always be 0. 0N/A * [Requires SD_LOCK_READ or SD_LOCK_WRITE] 0N/A * The pixel stride is the distance in bytes from the data for one pixel 0N/A * to the data for the pixel at the next x coordinate (x, y) => (x+1, y). 0N/A * For data types that pack multiple pixels into a byte, such as 0N/A * ByteBinary1Bit et al, this field will be 0 and the loops which 0N/A * render to and from such data need to calculate their own offset 0N/A * from the beginning of the scanline using the absolute x coordinate 0N/A * combined with the pixelBitOffset field. 0N/A * Bugfix 6220829 - this field used to be unsigned int, but some 0N/A * primitives used negative pixel offsets and the corresponding 0N/A * unsigned stride values caused the resulting pixel offset to 0N/A * to always be a positive 32-bit quantity - causing problems on 0N/A * 64-bit architectures. 0N/A * [Requires SD_LOCK_READ or SD_LOCK_WRITE] 0N/A * The scan stride is the distance in bytes from the data for one pixel 0N/A * to the data for the pixel at the next y coordinate (x, y) => (x, y+1). 0N/A * Bugfix 6220829 - this field used to be unsigned int, but some 0N/A * primitives used negative pixel offsets and the corresponding 0N/A * unsigned stride values caused the resulting pixel offset to 0N/A * to always be a positive 32-bit quantity - causing problems on 0N/A * 64-bit architectures. 0N/A * unsigned int lutSize; 0N/A * [Requires SD_LOCK_LUT] 0N/A * The number of entries in the color lookup table. The data beyond the 0N/A * end of the map will be undefined. 0N/A * [Requires SD_LOCK_LUT] 0N/A * A pointer to the beginning of the color lookup table for the colormap. 0N/A * The color lookup table is formatted as an array of jint values each 0N/A * representing the 32-bit ARGB color for the pixel representing by the 0N/A * corresponding index. The table is guaranteed to contain at least 256 0N/A * valid memory locations even if the size of the map is smaller than 256. 0N/A * unsigned char *invColorTable; 0N/A * [Requires SD_LOCK_INVCOLOR] 0N/A * A pointer to the beginning of the inverse color lookup table for the 0N/A * colormap. The inverse color lookup table is formatted as a 32x32x32 0N/A * array of bytes indexed by RxGxB where each component is reduced to 5 0N/A * bits of precision before indexing. 0N/A * char *redErrTable; 0N/A * char *grnErrTable; 0N/A * char *bluErrTable; 0N/A * [Requires SD_LOCK_INVCOLOR] 0N/A * Pointers to the beginning of the ordered dither color error tables 0N/A * for the colormap. The error tables are formatted as an 8x8 array 0N/A * of bytes indexed by coordinates using the formula [y & 7][x & 7]. 0N/A * int *invGrayTable; 0N/A * [Requires SD_LOCK_INVGRAY] 0N/A * A pointer to the beginning of the inverse gray lookup table for the 0N/A * colormap. The inverse color lookup table is formatted as an array 0N/A * of 256 integers indexed by a byte gray level and storing an index 0N/A * into the colormap of the closest matching gray pixel. 0N/A * A buffer of private data for the SurfaceData implementation. 0N/A * This field is a union of a data block of the desired default 0N/A * size (SD_RASINFO_PRIVATE_SIZE) and a (void *) pointer that 0N/A * ensures proper "strictest" alignment on all platforms. 0N/A void *
align;
/* ensures strict alignment */ 0N/A * This function is used to lock a particular region of a particular 0N/A * destination. Once this method is called, no changes of any of the 0N/A * data returned by any of the other SurfaceData vectored functions 0N/A * may change until a corresponding call to Release is made. 0N/A * The env parameter should be the JNIEnv of the surrounding JNI context. 0N/A * The ops parameter should be a pointer to the ops object upon which 0N/A * this function is being invoked. 0N/A * The rasInfo parameter should be a pointer to a SurfaceDataRasInfo 0N/A * structure in which the bounds have been initialized to the maximum 0N/A * bounds of the raster data that will need to be accessed later. 0N/A * The lockflags parameter should indicate which information will be 0N/A * needed by the caller. The various flags which may be OR'd together 0N/A * may consist of any of the following: 0N/A * SD_LOCK_READ The caller needs to read pixels from the dest 0N/A * SD_LOCK_WRITE The caller needs to write pixels to the dest 0N/A * SD_LOCK_RD_WR A combination of (SD_LOCK_READ | SD_LOCK_WRITE) 0N/A * SD_LOCK_LUT The caller needs the colormap (Lut) 0N/A * SD_LOCK_INVCOLOR The caller needs the inverse color table 0N/A * SD_LOCK_INVGRAY The caller needs the inverse gray table 0N/A * SD_LOCK_FASTEST The caller only wants direct pixel access 0N/A * Note that the SD_LOCK_LUT, SD_LOCK_INVCOLOR, and SD_LOCK_INVGRAY flags 0N/A * are only valid for destinations with IndexColorModels. 0N/A * Also note that SD_LOCK_FASTEST will only succeed if the access to the 0N/A * pixels will occur just as fast regardless of the size of the bounds. 0N/A * This flag is used by the Text rendering routines to determine if it 0N/A * matters whether or not they have calculated a tight bounding box for 0N/A * the pixels they will be touching. 0N/A * If this function succeeds, it will return SD_SUCCESS (0). 0N/A * If this function is unable to honor the SD_LOCK_FASTEST flag, 0N/A * it will return SD_SLOWLOCK. The bounds parameter of the 0N/A * SurfaceDataRasInfo object should be intersected with a tighter 0N/A * bounding rectangle before calling the GetRasInfo function so 0N/A * as to minimize the amount pixel copying or conversion. Note 0N/A * that the Lock function may have already intersected the 0N/A * bounds with a tighter rectangle as it tried to honor the 0N/A * SD_SLOWLOCK flag and so the caller should only use intersection 0N/A * operations to further restrict the bounds. 0N/A * If this function fails for any reason that is not recoverable, 0N/A * it will throw an appropriate Java exception and return SD_FAILED. 0N/A * This function will intersect the bounds specified in the rasInfo 0N/A * parameter with the available raster data in the destination drawable 0N/A * and modify the contents of the bounds field to represent the maximum 0N/A * available raster data. 0N/A * If the available raster data in the destination drawable consists of 0N/A * a non-rectangular region of pixels, this method may throw an InvalidPipe 0N/A * exception (optionally the object may decide to provide a copy of the 0N/A * destination pixel data with undefined data in the inaccessible portions). 0N/A * Further processing by the caller may discover that a smaller region of 0N/A * data is actually needed and the call to GetRasData can be made with a 0N/A * still smaller bounds. 0N/A * This function may use JNI methods so it is important that the 0N/A * caller not have any outstanding GetPrimitiveArrayCritical or 0N/A * GetStringCritical locks which have not been released. 0N/A * Note to implementers: 0N/A * The caller may also continue to use JNI methods after this method 0N/A * is called so it is important that implementations of SurfaceData 0N/A * not return from this function with any outstanding JNI Critical 0N/A * locks that have not been released. 0N/A * This function returns information about the raster data for the drawable. 0N/A * The function will fill in or modify the contents of the SurfaceDataRasInfo 0N/A * structure that is passed in with various pieces of information depending 0N/A * on what was requested in the lockflags parameter that was handed into 0N/A * the LockFunc. For more information on which pieces of information are 0N/A * returned based upon the lock flags see the documentation for the 0N/A * RasInfo structure above. 0N/A * The env parameter should be the JNIEnv of the surrounding JNI context. 0N/A * The ops parameter should be a pointer to the ops object upon which 0N/A * this function is being invoked. 0N/A * The pRasInfo parameter should be a pointer to the same structure of type 0N/A * SurfaceDataRasInfo. The bounds member of that structure should be 0N/A * initialized to the bounding box of the raster data that is actually 0N/A * needed for reading or writing before calling this function. These 0N/A * bounds must be a subset of the raster bounds that were given to the 0N/A * LockFunc or the results will be undefined. 0N/A * If the surface was locked with the flag SD_LOCK_FASTEST then this 0N/A * function may reevaluate the bounds in the RasInfo structure and 0N/A * return a subset of what was requested. Callers that use that flag 0N/A * should be prepared to reevaluate their clipping after GetRasInfo 0N/A * returns. If the SD_LOCK_FASTEST flag was not specified, then this 0N/A * function will return a buffer containing all of the pixels in the 0N/A * requested bounds without reevaluating them. 0N/A * Any information that was requested in the lockflags of the LockFunc 0N/A * will be returned and NULL pointers will be returned for all other 0N/A * This function may use JNI Critical methods so it is important 0N/A * that the caller not call any other JNI methods after this function 0N/A * returns until the Release function is called. 0N/A * This function releases all of the Critical data for the specified 0N/A * This function vector is allowed to be NULL if a given SurfaceData 0N/A * implementation does not require the use of JNI Critical array locks. 0N/A * Callers should use the "SurfaceData_InvokeRelease(env, ops)" macro 0N/A * to handle the conditional invocation of this function. 0N/A * In particular, this function will release any outstanding JNI Critical 0N/A * locks that the SurfaceData implementation may have used so that it 0N/A * will be safe for the caller to start using arbitrary JNI calls or 0N/A * return from its calling JNI function. 0N/A * The env parameter should be the JNIEnv of the surrounding JNI context. 0N/A * The ops parameter should be a pointer to the ops object upon which 0N/A * this function is being invoked. 0N/A * The pRasInfo parameter should be a pointer to the same structure of 0N/A * type SurfaceDataRasInfo that was passed to the GetRasInfo function. 0N/A * The bounds should be unchanged since that call. 0N/A * This function will release any outstanding JNI Critical locks so 0N/A * it will once again be safe to use arbitrary JNI calls or return 0N/A * to the enclosing JNI native context. 0N/A * Note to implementers: 0N/A * This function may not use any JNI methods other than to release 0N/A * outstanding JNI Critical array locks since there may be other 0N/A * nested SurfacData objects holding locks with their own outstanding 0N/A * JNI Critical locks. This restriction includes the use of the 0N/A * JNI monitor calls so that all MonitorExit invocations must be 0N/A * done in the Unlock function. 0N/A * This function unlocks the specified drawable. 0N/A * This function vector is allowed to be NULL if a given SurfaceData 0N/A * implementation does not require any unlocking of the destination. 0N/A * Callers should use the "SurfaceData_InvokeUnlock(env, ops)" macro 0N/A * to handle the conditional invocation of this function. 0N/A * The env parameter should be the JNIEnv of the surrounding JNI context. 0N/A * The ops parameter should be a pointer to the ops object upon which 0N/A * this function is being invoked. 0N/A * The pRasInfo parameter should be a pointer to the same structure of 0N/A * type SurfaceDataRasInfo that was passed to the GetRasInfo function. 0N/A * The bounds should be unchanged since that call. 0N/A * This function may use JNI methods so it is important that the 0N/A * caller not have any outstanding GetPrimitiveArrayCritical or 0N/A * GetStringCritical locks which have not been released. 0N/A * Note to implementers: 0N/A * This function may be used to release any JNI monitors used to 0N/A * prevent the destination from being modified. It may also be 0N/A * used to perform operations which may require blocking (such as 0N/A * executing X11 operations which may need to flush data). 0N/A * This function sets up the specified drawable. Some surfaces may 0N/A * need to perform certain operations during Setup that cannot be 0N/A * done after later operations such as Lock. For example, on 0N/A * win9x systems, when any surface is locked we cannot make a call to 0N/A * the message-handling thread. 0N/A * This function vector is allowed to be NULL if a given SurfaceData 0N/A * implementation does not require any setup. 0N/A * The env parameter should be the JNIEnv of the surrounding JNI context. 0N/A * The ops parameter should be a pointer to the ops object upon which 0N/A * this function is being invoked. 0N/A * This function may use JNI methods so it is important that the 0N/A * caller not have any outstanding GetPrimitiveArrayCritical or 0N/A * GetStringCritical locks which have not been released. 0N/A * This function disposes the specified SurfaceDataOps structure 0N/A * and associated native resources. 0N/A * The implementation is SurfaceData-type specific. 0N/A * Constants used for return values. Constants less than 0 are 0N/A * unrecoverable failures and indicate that a Java exception has 0N/A * already been thrown. Constants greater than 0 are conditional 0N/A * successes which warn the caller that various optional features 0N/A * were not available so that workarounds can be used. 0N/A * Constants for the flags used in the Lock function. 0N/A * This structure provides the function vectors for manipulating 0N/A * and retrieving information about the destination drawable. 0N/A * There are also variables for the surface data object used by 0N/A * native code to track the state of the surface. 0N/A * The sdObject is a pointer to the Java SurfaceData object; 0N/A * this is set in SurfaceData_InitOps() and used by any object 0N/A * using the ops structure to refer to elements in the Java object 0N/A * (such as fields that we need to set from native code). 0N/A * This macro performs a lookup in an inverse color table given 3 8-bit 0N/A * RGB primaries. It automates the process of reducing the primaries 0N/A * to 5-bits of precision and using them to index into the specified 0N/A * inverse color lookup table. 0N/A * This macro invokes the SurfaceData Release function only if the 0N/A * function vector is not NULL. 0N/A * This macro invokes the SurfaceData Unlock function only if the 0N/A * function vector is not NULL. 0N/A * This macro invokes both the SurfaceData Release and Unlock functions 0N/A * only if the function vectors are not NULL. It can be used in cases 0N/A * where only one surface has been accessed and where no other JNI 0N/A * Critical locks (which would need to be released after Release and 0N/A * before Unlock) are held by the calling function. 0N/A * This macro invokes both the SurfaceData Release and Unlock functions 0N/A * on two nested drawables only if the function vectors are not NULL. 0N/A * It can be used in cases where two surfaces have been accessed and 0N/A * where no other JNI Critical locks (which would need to be released 0N/A * after Release and before Unlock) are held by the calling function. The 0N/A * two ops vectors should be specified in the same order that they were 0N/A * locked. Both surfaces will be released and then both unlocked. 0N/A * This function returns a pointer to a native SurfaceDataOps 0N/A * structure for accessing the indicated SurfaceData Java object. 0N/A * This function uses JNI methods so it is important that the 0N/A * caller not have any outstanding GetPrimitiveArrayCritical or 0N/A * GetStringCritical locks which have not been released. 0N/A * The caller may continue to use JNI methods after this method 0N/A * is called since this function will not leave any outstanding 0N/A * JNI Critical locks unreleased. 0N/A * Does the same as the above, but doesn't call Setup function 0N/A * This function stores a pointer to a native SurfaceDataOps 0N/A * structure into the indicated Java SurfaceData object. 0N/A * This function uses JNI methods so it is important that the 0N/A * caller not have any outstanding GetPrimitiveArrayCritical or 0N/A * GetStringCritical locks which have not been released. 0N/A * The caller may continue to use JNI methods after this method 0N/A * is called since this function will not leave any outstanding 0N/A * JNI Critical locks unreleased. 0N/A * This function throws an InvalidPipeException which will cause the 0N/A * calling SunGraphics2D object to revalidate its pipelines and call 0N/A * again. This utility method should be called from the SurfaceData 0N/A * native Lock routine when some attribute of the surface has changed 0N/A * that requires pipeline revalidation, including: 0N/A * The bit depth or pixel format of the surface. 0N/A * The surface (window) has been disposed. 0N/A * The device clip of the surface has been changed (resize, visibility, etc.) 0N/A * This function uses JNI methods so it is important that the 0N/A * caller not have any outstanding GetPrimitiveArrayCritical or 0N/A * GetStringCritical locks which have not been released. 0N/A * The caller may continue to use JNI methods after this method 0N/A * is called since this function will not leave any outstanding 0N/A * JNI Critical locks unreleased. 0N/A * This function intersects two bounds objects which exist in the same 0N/A * coordinate space. The contents of the first parameter (dst) are 0N/A * modified to contain the intersection of the two bounds while the 0N/A * contents of the second parameter (src) are untouched. 0N/A * This function intersects a bounds object with a rectangle specified 0N/A * in lox, loy, hix, hiy format in the same coordinate space. The 0N/A * contents of the first parameter (bounds) are modified to contain 0N/A * the intersection of the two rectangular regions. 0N/A * This function intersects a bounds object with a rectangle specified 0N/A * in XYWH format in the same coordinate space. The contents of the 0N/A * first parameter (bounds) are modified to contain the intersection 0N/A * of the two rectangular regions. 0N/A * This function intersects two bounds objects which exist in different 0N/A * coordinate spaces. The coordinate spaces of the two objects are 0N/A * related such that a given coordinate in the space of the A bounds 0N/A * is related to the analogous coordinate in the space of the B bounds 0N/A * by the formula: (AX + BXminusAX, AY + BYminusAY) == (BX, BY). 0N/A * The contents of both bounds objects are modified to represent their 0N/A * mutual intersection. 0N/A * This function creates and initializes the ops structure. The function 0N/A * is called by "subclasses" of SurfaceData (e.g., BufImgSurfaceData) 0N/A * which pass in the size of the structure to allocate (subclasses generally 0N/A * need additional fields in the ops structure particular to their usage 0N/A * of the structure). The structure is allocated and initialized 0N/A * and is stored in the SurfaceData java object for later retrieval. 0N/A * Subclasses of SurfaceData should call this function instead of allocating 0N/A * the memory directly. 0N/A * This function invokes the ops-specific disposal function. 0N/A * It is a part of the finalizers-free disposal mechanism. 0N/A * (see Disposer and DefaultDisposerRecord classes for more information) 0N/A * It also destroys the ops structure created in SurfaceData_InitOps.