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