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