Java example source code file (Region.h)

This example Java source code file (Region.h) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

jnicall, jniexport, rect_t, region_enditeration, region_getbounds, region_getinfo, region_intersectboundsxyxy, region_isempty, region_isrectangular, region_nextiteration, regiondata, regiontoyxbandedrectangles, surfacedata_intersectbounds, surfacedatabounds

The Region.h Java example source code

/*
 * Copyright (c) 2002, 2007, 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.
 */

#ifndef _Included_Region
#define _Included_Region

#ifdef __cplusplus
extern "C" {
#endif

#include <SurfaceData.h>
#include "utility/rect.h"


/*
 * This file provides a number of structures, macros, and C functions
 * for native code to use to iterate through the list of rectangles
 * included in a Java Region object.  The intended usage pattern should
 * comply with the following code sample:
 *
 *      RegionData rgnInfo;
 *      Region_GetInfo(env, javaregion, &rgnInfo);
 *      // Calculate the area of interest for the graphics operation.
 *      Region_IntersectBounds(&rgnInfo, lox, loy, hix, hiy);
 *      if (!Region_IsEmpty(&rgnInfo)) {
 *              If (Region_IsRectangular(&rgnInfo)) {
 *                      // Optional code optimized for a single rectangle
 *              } else {
 *                      SurfaceDataBounds span;
 *                      Region_StartIteration(env, &rgnInfo);
 *                      // this next line is optional if the info is needed
 *                      int numrects = Region_CountIterationRects(&rgnInfo);
 *                      while (Region_NextIteration(&rgnInfo, &span)) {
 *                              // Process span.x1, span.y1, span.x2, span.y2
 *                      }
 *                      Region_EndIteration(env, &rgnInfo);
 *              }
 *      }
 */

/*
 * This structure is not meant to be accessed by code outside of
 * Region.h or Region.c.  It is exposed here so that callers can
 * stack-allocate one of these structures for performance.
 */
typedef struct {
    SurfaceDataBounds   bounds;
    jint                endIndex;
    jobject             bands;
    jint                index;
    jint                numrects;
    jint                *pBands;
} RegionData;

/*
 * Initialize a native RegionData structure from a Java object
 * of type sun.java2d.pipe.Region.
 *
 * 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.
 */
JNIEXPORT jint JNICALL
Region_GetInfo(JNIEnv *env, jobject region, RegionData *pRgnInfo);

/*
 * This function retrieves the bounds from a Java Region object and
 * returns them in the specified SurfaceDataBounds structure.
 *
 * 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.
 */
JNIEXPORT void JNICALL
Region_GetBounds(JNIEnv *env, jobject region, SurfaceDataBounds *b);

/*
 * Intersect the specified SurfaceDataBounds with the bounds of
 * the indicated RegionData structure.  The Region iteration will
 * subsequently honor those bounds.
 */
#define Region_IntersectBounds(pRgnInfo, pDstBounds) \
    SurfaceData_IntersectBounds(&(pRgnInfo)->bounds, pDstBounds)

/*
 * Intersect the specified bounding coordinates with the bounds of
 * the indicated RegionData structure.  The Region iteration will
 * subsequently honor those bounds.
 */
#define Region_IntersectBoundsXYXY(pRgnInfo, x1, y1, x2, y2) \
    SurfaceData_IntersectBoundsXYXY(&(pRgnInfo)->bounds, x1, y1, x2, y2)

/*
 * Test whether the bounds of the specified RegionData structure
 * are now trivially empty.
 *
 * Note that this test only checks the overall bounds of the Region
 * and does not check to see if there are any individual subrectangles
 * which make up the region that intersect the current bounds.
 * Typically a Java Region object will have tight bounds that reflects
 * a non-empty set of subrectangles in the list, but after a given
 * graphics operation has intersected the RegionData with the area
 * of interest for that operation using one of the above calls to
 * IntersectBounds, the new bounds may fail to intersect any of
 * the subrectangles.
 */
#define Region_IsEmpty(pRgnInfo) \
    ((pRgnInfo)->bounds.x1 >= (pRgnInfo)->bounds.x2 || \
     (pRgnInfo)->bounds.y1 >= (pRgnInfo)->bounds.y2)

/*
 * Test whether the RegionData structure represents a single rectangle.
 *
 * Note that this test only checks to see if the original Java Region
 * object is a simple rectangle and does not take into account the
 * subsetting of the list of rectangles that might occur if a given
 * graphics operation intersects the bounds with an area of interest.
 */
#define Region_IsRectangular(pRgnInfo) \
    ((pRgnInfo)->endIndex == 0)

/*
 * Initialize a given RegionData structure for iteration of the
 * list of subrectangles.  This operation can be performed on
 * empty regions, simple rectangular regions and complex regions
 * without loss of generality.
 *
 * 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 RegionEndIteration function is called.
 */
JNIEXPORT void JNICALL
Region_StartIteration(JNIEnv *env, RegionData *pRgnInfo);

/*
 * Count the number of subrectangles in the indicated RegionData.
 * The subrectangles will be compared against the bounds of the
 * Region so only those subrectangles that intersect the area of
 * interest will be included in the returned count.
 *
 * Note to callers:
 *      This function may only be called after Region_StartIteration
 *      and before Region_EndIteration are called on a given RegionData
 *      structure.
 */
JNIEXPORT jint JNICALL
Region_CountIterationRects(RegionData *pRgnInfo);

/*
 * Process the list of subrectangles in the RegionData structure and
 * assign the bounds of that subrectangle to the pSpan structure and
 * return a non-zero return value if one exists.  If there are no
 * more subrectangles in the given area of interest specified by
 * the bounds of the RegionData structure, then return 0.
 *
 * Note to callers:
 *      This function may only be called after Region_StartIteration
 *      and before Region_EndIteration are called on a given RegionData
 *      structure.
 */
JNIEXPORT jint JNICALL
Region_NextIteration(RegionData *pRgnInfo, SurfaceDataBounds *pSpan);

/*
 * Uninitialize a RegionData structure and discard any information
 * that was needed to iterate the list of subrectangles.
 *
 * 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.
 */
JNIEXPORT void JNICALL
Region_EndIteration(JNIEnv *env, RegionData *pRgnInfo);


/*
 * Converts a sun.java2d.pipe.Region object to a list of
 * rectangles using platform specific native data representation
 * (see the src/$PLATFORM/native/sun/awt/utility/rect.h header
 * files.)
 */
JNIEXPORT int JNICALL
RegionToYXBandedRectangles(JNIEnv *env,
        jint x1, jint y1, jint x2, jint y2, jobject region,
        RECT_T ** pRect, unsigned int initialBufferSize);


#ifdef __cplusplus
};
#endif

#endif