1/*
2 * Copyright (c) 2002, 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#ifndef _Included_Region
27#define _Included_Region
28
29#ifdef __cplusplus
30extern "C" {
31#endif
32
33#include <SurfaceData.h>
34#include "utility/rect.h"
35
36
37/*
38 * This file provides a number of structures, macros, and C functions
39 * for native code to use to iterate through the list of rectangles
40 * included in a Java Region object.  The intended usage pattern should
41 * comply with the following code sample:
42 *
43 *      RegionData rgnInfo;
44 *      Region_GetInfo(env, javaregion, &rgnInfo);
45 *      // Calculate the area of interest for the graphics operation.
46 *      Region_IntersectBounds(&rgnInfo, lox, loy, hix, hiy);
47 *      if (!Region_IsEmpty(&rgnInfo)) {
48 *              If (Region_IsRectangular(&rgnInfo)) {
49 *                      // Optional code optimized for a single rectangle
50 *              } else {
51 *                      SurfaceDataBounds span;
52 *                      Region_StartIteration(env, &rgnInfo);
53 *                      // this next line is optional if the info is needed
54 *                      int numrects = Region_CountIterationRects(&rgnInfo);
55 *                      while (Region_NextIteration(&rgnInfo, &span)) {
56 *                              // Process span.x1, span.y1, span.x2, span.y2
57 *                      }
58 *                      Region_EndIteration(env, &rgnInfo);
59 *              }
60 *      }
61 */
62
63/*
64 * This structure is not meant to be accessed by code outside of
65 * Region.h or Region.c.  It is exposed here so that callers can
66 * stack-allocate one of these structures for performance.
67 */
68typedef struct {
69    SurfaceDataBounds   bounds;
70    jint                endIndex;
71    jobject             bands;
72    jint                index;
73    jint                numrects;
74    jint                *pBands;
75} RegionData;
76
77/*
78 * Initialize a native RegionData structure from a Java object
79 * of type sun.java2d.pipe.Region.
80 *
81 * Note to callers:
82 *      This function may use JNI methods so it is important that the
83 *      caller not have any outstanding GetPrimitiveArrayCritical or
84 *      GetStringCritical locks which have not been released.
85 */
86JNIEXPORT jint JNICALL
87Region_GetInfo(JNIEnv *env, jobject region, RegionData *pRgnInfo);
88
89/*
90 * This function retrieves the bounds from a Java Region object and
91 * returns them in the specified SurfaceDataBounds structure.
92 *
93 * Note to callers:
94 *      This function may use JNI methods so it is important that the
95 *      caller not have any outstanding GetPrimitiveArrayCritical or
96 *      GetStringCritical locks which have not been released.
97 */
98JNIEXPORT void JNICALL
99Region_GetBounds(JNIEnv *env, jobject region, SurfaceDataBounds *b);
100
101/*
102 * Intersect the specified SurfaceDataBounds with the bounds of
103 * the indicated RegionData structure.  The Region iteration will
104 * subsequently honor those bounds.
105 */
106#define Region_IntersectBounds(pRgnInfo, pDstBounds) \
107    SurfaceData_IntersectBounds(&(pRgnInfo)->bounds, pDstBounds)
108
109/*
110 * Intersect the specified bounding coordinates with the bounds of
111 * the indicated RegionData structure.  The Region iteration will
112 * subsequently honor those bounds.
113 */
114#define Region_IntersectBoundsXYXY(pRgnInfo, x1, y1, x2, y2) \
115    SurfaceData_IntersectBoundsXYXY(&(pRgnInfo)->bounds, x1, y1, x2, y2)
116
117/*
118 * Test whether the bounds of the specified RegionData structure
119 * are now trivially empty.
120 *
121 * Note that this test only checks the overall bounds of the Region
122 * and does not check to see if there are any individual subrectangles
123 * which make up the region that intersect the current bounds.
124 * Typically a Java Region object will have tight bounds that reflects
125 * a non-empty set of subrectangles in the list, but after a given
126 * graphics operation has intersected the RegionData with the area
127 * of interest for that operation using one of the above calls to
128 * IntersectBounds, the new bounds may fail to intersect any of
129 * the subrectangles.
130 */
131#define Region_IsEmpty(pRgnInfo) \
132    ((pRgnInfo)->bounds.x1 >= (pRgnInfo)->bounds.x2 || \
133     (pRgnInfo)->bounds.y1 >= (pRgnInfo)->bounds.y2)
134
135/*
136 * Test whether the RegionData structure represents a single rectangle.
137 *
138 * Note that this test only checks to see if the original Java Region
139 * object is a simple rectangle and does not take into account the
140 * subsetting of the list of rectangles that might occur if a given
141 * graphics operation intersects the bounds with an area of interest.
142 */
143#define Region_IsRectangular(pRgnInfo) \
144    ((pRgnInfo)->endIndex == 0)
145
146/*
147 * Initialize a given RegionData structure for iteration of the
148 * list of subrectangles.  This operation can be performed on
149 * empty regions, simple rectangular regions and complex regions
150 * without loss of generality.
151 *
152 * Note to callers:
153 *      This function may use JNI Critical methods so it is important
154 *      that the caller not call any other JNI methods after this function
155 *      returns until the RegionEndIteration function is called.
156 */
157JNIEXPORT void JNICALL
158Region_StartIteration(JNIEnv *env, RegionData *pRgnInfo);
159
160/*
161 * Count the number of subrectangles in the indicated RegionData.
162 * The subrectangles will be compared against the bounds of the
163 * Region so only those subrectangles that intersect the area of
164 * interest will be included in the returned count.
165 *
166 * Note to callers:
167 *      This function may only be called after Region_StartIteration
168 *      and before Region_EndIteration are called on a given RegionData
169 *      structure.
170 */
171JNIEXPORT jint JNICALL
172Region_CountIterationRects(RegionData *pRgnInfo);
173
174/*
175 * Process the list of subrectangles in the RegionData structure and
176 * assign the bounds of that subrectangle to the pSpan structure and
177 * return a non-zero return value if one exists.  If there are no
178 * more subrectangles in the given area of interest specified by
179 * the bounds of the RegionData structure, then return 0.
180 *
181 * Note to callers:
182 *      This function may only be called after Region_StartIteration
183 *      and before Region_EndIteration are called on a given RegionData
184 *      structure.
185 */
186JNIEXPORT jint JNICALL
187Region_NextIteration(RegionData *pRgnInfo, SurfaceDataBounds *pSpan);
188
189/*
190 * Uninitialize a RegionData structure and discard any information
191 * that was needed to iterate the list of subrectangles.
192 *
193 * Note to callers:
194 *      This function will release any outstanding JNI Critical locks so
195 *      it will once again be safe to use arbitrary JNI calls or return
196 *      to the enclosing JNI native context.
197 */
198JNIEXPORT void JNICALL
199Region_EndIteration(JNIEnv *env, RegionData *pRgnInfo);
200
201
202/*
203 * Converts a sun.java2d.pipe.Region object to a list of
204 * rectangles using platform specific native data representation
205 * (see the src/$PLATFORM/native/sun/awt/utility/rect.h header
206 * files.)
207 */
208JNIEXPORT int JNICALL
209RegionToYXBandedRectangles(JNIEnv *env,
210        jint x1, jint y1, jint x2, jint y2, jobject region,
211        RECT_T ** pRect, unsigned int initialBufferSize);
212
213
214#ifdef __cplusplus
215};
216#endif
217
218#endif
219