1 /*
2 * Copyright (c) 1999, 2020, 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 This file contains routines for manipulating generic lists.
27 Lists are implemented with a "harness". In other words, each
28 node in the list consists of two pointers, one to the data item
29 and one to the next node in the list. The head of the list is
30 the same struct as each node, but the "item" ptr is used to point
31 to the current member of the list (used by the first_in_list and
32 next_in_list functions).
33
34 This file is available under and governed by the GNU General Public
35 License version 2 only, as published by the Free Software Foundation.
36 However, the following notice accompanied the original version of this
37 file:
38
39 Copyright 1994 Hewlett-Packard Co.
40 Copyright 1996, 1998 The Open Group
41
42 Permission to use, copy, modify, distribute, and sell this software and its
43 documentation for any purpose is hereby granted without fee, provided that
44 the above copyright notice appear in all copies and that both that
45 copyright notice and this permission notice appear in supporting
46 documentation.
47
48 The above copyright notice and this permission notice shall be included
49 in all copies or substantial portions of the Software.
50
51 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
52 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
53 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
54 IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
55 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
56 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
57 OTHER DEALINGS IN THE SOFTWARE.
58
59 Except as contained in this notice, the name of The Open Group shall
60 not be used in advertising or otherwise to promote the sale, use or
61 other dealings in this Software without prior written authorization
62 from The Open Group.
63
64 ------------------------------------------------------------------------ **/
65
66 /******************************************************************************
67 *
68 * This file contains various typedef's, macros and procedure declarations for
69 * a set of example utility procedures contained in the file "wsutils.c".
70 *
71 ******************************************************************************/
72
73 #ifdef HEADLESS
74 #error This file should not be included in headless library
75 #endif
76
77 typedef unsigned long Pixel;
78
79 /* This is the actual structure returned by the X server describing the
80 * SERVER_OVERLAY_VISUAL property.
81 */
82 typedef struct
83 {
84 VisualID visualID; /* The VisualID of the overlay visual */
85 int transparentType; /* Can be None, TransparentPixel or
86 * TransparentMask */
87 Pixel value; /* Pixel value */
88 int layer; /* Overlay planes will always be in
89 * layer 1 */
90 } OverlayVisualPropertyRec;
91
92
93 /* This is structure also describes the SERVER_OVERLAY_VISUAL property, but
94 * should be more useful than the one actually returned by the X server
95 * because it actually points to the visual's XVisualInfo struct rather than
96 * refering to the visual's ID.
97 */
98 typedef struct
99 {
100 XVisualInfo *pOverlayVisualInfo; /* Pointer to the XVisualInfo struct */
101 int transparentType; /* Can be None, TransparentPixel or
102 * TransparentMask */
103 Pixel value; /* Pixel value */
104 int layer; /* Overlay planes will always be in
105 * layer 1 */
106 } OverlayInfo;
107
108
109 /* These macros are the values of the "transparentType" above: */
110 #ifndef None
111 #define None 0
112 #endif
113 #ifndef TransparentPixel
114 #define TransparentPixel 1
115 #endif
116
117
118 /* These macros define how flexible a program is when it requests a window's
119 * creation with either the CreateImagePlanesWindow() or
120 * CreateOverlayPlanesWindow():
121 */
122 #ifndef NOT_FLEXIBLE
123 #define NOT_FLEXIBLE 0
124 #define FLEXIBLE 1
125 #endif
126
127
128 /* These macros define the values of the "sbCmapHint" parameter of the
129 * CreateImagePlanesWindow():
130 */
131 #ifndef SB_CMAP_TYPE_NORMAL
132 #define SB_CMAP_TYPE_NORMAL 1
133 #endif
134
135 #ifndef SB_CMAP_TYPE_MONOTONIC
136 #define SB_CMAP_TYPE_MONOTONIC 2
137 #endif
138
139 #ifndef SB_CMAP_TYPE_FULL
140 #define SB_CMAP_TYPE_FULL 4
141 #endif
142
143
144 /******************************************************************************
145 *
146 * GetXVisualInfo()
147 *
148 * This routine takes an X11 Display, screen number, and returns whether the
149 * screen supports transparent overlays and three arrays:
150 *
151 * 1) All of the XVisualInfo struct's for the screen.
152 * 2) All of the OverlayInfo struct's for the screen.
153 * 3) An array of pointers to the screen's image plane XVisualInfo
154 * structs.
155 *
156 * The code below obtains the array of all the screen's visuals, and obtains
157 * the array of all the screen's overlay visual information. It then processes
158 * the array of the screen's visuals, determining whether the visual is an
159 * overlay or image visual.
160 *
161 * If the routine sucessfully obtained the visual information, it returns zero.
162 * If the routine didn't obtain the visual information, it returns non-zero.
163 *
164 ******************************************************************************/
165
166 extern int GetXVisualInfo(
167 Display *display, /* Which X server (aka "display"). */
168 int screen, /* Which screen of the "display". */
169 int *transparentOverlays, /* Non-zero if there's at least one
170 * overlay visual and if at least one
171 * of those supports a transparent
172 * pixel. */
173 int *numVisuals, /* Number of XVisualInfo struct's
174 * pointed to to by pVisuals. */
175 XVisualInfo **pVisuals, /* All of the device's visuals. */
176 int *numOverlayVisuals, /* Number of OverlayInfo's pointed
177 * to by pOverlayVisuals. If this
178 * number is zero, the device does
179 * not have overlay planes. */
180 OverlayInfo **pOverlayVisuals, /* The device's overlay plane visual
181 * information. */
182 int *numImageVisuals, /* Number of XVisualInfo's pointed
183 * to by pImageVisuals. */
184 XVisualInfo ***pImageVisuals /* The device's image visuals. */
185 );
186
187
188 /******************************************************************************
189 *
190 * FreeXVisualInfo()
191 *
192 * This routine frees the data that was allocated by GetXVisualInfo().
193 *
194 ******************************************************************************/
195
196 extern void FreeXVisualInfo(
197 XVisualInfo *pVisuals,
198 OverlayInfo *pOverlayVisuals,
199 XVisualInfo **pImageVisuals
200 );
201
202
203 /******************************************************************************
204 *
205 * FindImagePlanesVisual()
206 *
207 * This routine attempts to find a visual to use to create an image planes
208 * window based upon the information passed in.
209 *
210 * The "Hint" values give guides to the routine as to what the program wants.
211 * The "depthFlexibility" value tells the routine how much the program wants
212 * the actual "depthHint" specified. If the program can't live with the
213 * screen's image planes visuals, the routine returns non-zero, and the
214 * "depthObtained" and "pImageVisualToUse" return parameters are NOT valid.
215 * Otherwise, the "depthObtained" and "pImageVisualToUse" return parameters
216 * are valid and the routine returns zero.
217 *
218 * NOTE: This is just an example of what can be done. It may or may not be
219 * useful for any specific application.
220 *
221 ******************************************************************************/
222
223 extern int FindImagePlanesVisual(
224 Display *display, /* Which X server (aka "display"). */
225 int screen, /* Which screen of the "display". */
226 int numImageVisuals, /* Number of XVisualInfo's pointed
227 * to by pImageVisuals. */
228 XVisualInfo **pImageVisuals, /* The device's image visuals. */
229 int sbCmapHint, /* What Starbase cmap modes will be
230 * used with the visual. NOTE: This
231 * is a mask of the possible values. */
232 int depthHint, /* Desired depth. */
233 int depthFlexibility, /* How much the actual value in
234 * "depthHint" is desired. */
235 Visual **pImageVisualToUse, /* The screen's image visual to use. */
236 int *depthObtained /* Actual depth of the visual. */
237 );
238
239
240 /******************************************************************************
241 *
242 * FindOverlayPlanesVisual()
243 *
244 * This routine attempts to find a visual to use to create an overlay planes
245 * window based upon the information passed in.
246 *
247 * While the CreateImagePlanesWindow() routine took a sbCmapHint, this
248 * routine doesn't. Starbase's CMAP_FULL shouldn't be used in overlay planes
249 * windows. This is partially because this functionality is better suited in
250 * the image planes where there are generally more planes, and partially
251 * because the overlay planes generally have PseudoColor visuals with one
252 * color being transparent (the transparent normally being the "white" color
253 * for CMAP_FULL).
254 *
255 * The "depthHint" values give guides to the routine as to what depth the
256 * program wants the window to be. The "depthFlexibility" value tells the
257 * routine how much the program wants the actual "depthHint" specified. If
258 * the program can't live with the screen's overlay planes visuals, the
259 * routine returns non-zero, and the "depthObtained" and "pOverlayVisualToUse"
260 * return parameters are NOT valid. Otherwise, the "depthObtained" and
261 * "pOverlayVisualToUse" return parameters are valid and the routine returns
262 * zero.
263 *
264 * NOTE: This is just an example of what can be done. It may or may not be
265 * useful for any specific application.
266 *
267 ******************************************************************************/
268
269 extern int FindOverlayPlanesVisual(
270 Display *display, /* Which X server (aka "display"). */
271 int screen, /* Which screen of the "display". */
272 int numOverlayVisuals, /* Number of OverlayInfo's pointed
273 * to by pOverlayVisuals. */
274 OverlayInfo *pOverlayVisuals, /* The device's overlay plane visual
275 * information. */
276 int depthHint, /* Desired depth. */
277 int depthFlexibility, /* How much the actual value in
278 * "depthHint" is desired. */
279 int transparentBackground, /* Non-zero if the visual must have
280 * a transparent color. */
281 Visual **pOverlayVisualToUse, /* The screen's overlay visual to
282 * use. */
283 int *depthObtained, /* Actual depth of the visual. */
284 int *transparentColor /* The transparent color the program
285 * can use with the visual. */
286 );
287
288
289 /******************************************************************************
290 *
291 * CreateImagePlanesWindow()
292 *
293 * This routine creates an image planes window, potentially creates a colormap
294 * for the window to use, and sets the window's standard properties, based
295 * upon the information passed in to the routine. While "created," the window
296 * has not been mapped.
297 *
298 * If the routine suceeds, it returns zero and the return parameters
299 * "imageWindow", "imageColormap" and "mustFreeImageColormap" are valid.
300 * Otherwise, the routine returns non-zero and the return parameters are
301 * NOT valid.
302 *
303 * NOTE: This is just an example of what can be done. It may or may not be
304 * useful for any specific application.
305 *
306 ******************************************************************************/
307
308 extern int CreateImagePlanesWindow(
309 Display *display, /* Which X server (aka "display"). */
310 int screen, /* Which screen of the "display". */
311 Window parentWindow, /* Window ID of the parent window for
312 * the created window. */
313 int windowX, /* Desired X coord. of the window. */
314 int windowY, /* Desired Y coord of the window. */
315 int windowWidth, /* Desired width of the window. */
316 int windowHeight, /* Desired height of the window. */
317 int windowDepth, /* Desired depth of the window. */
318 Visual *pImageVisualToUse, /* The window's image planes visual. */
319 int argc, /* Program's argc parameter. */
320 char *argv[], /* Program's argv parameter. */
321 char *windowName, /* Name to put on window's border. */
322 char *iconName, /* Name to put on window's icon. */
323 Window *imageWindow, /* Window ID of the created window. */
324 Colormap *imageColormap, /* The window's colormap. */
325 int *mustFreeImageColormap /* Non-zero if the program must call
326 * XFreeColormap() for imageColormap. */
327 );
328
329
330 /******************************************************************************
331 *
332 * CreateOverlayPlanesWindow()
333 *
334 * This routine creates an overlay planes window, potentially creates a colormap
335 * for the window to use, and sets the window's standard properties, based
336 * upon the information passed in to the routine. While "created," the window
337 * has not been mapped.
338 *
339 * If the routine suceeds, it returns zero and the return parameters
340 * "overlayWindow", "overlayColormap" and "mustFreeOverlayColormap" are valid.
341 * Otherwise, the routine returns non-zero and the return parameters are
342 * NOT valid.
343 *
344 * NOTE: This is just an example of what can be done. It may or may not be
345 * useful for any specific application.
346 *
347 ******************************************************************************/
348
349 int CreateOverlayPlanesWindow(
350 Display *display, /* Which X server (aka "display"). */
351 int screen, /* Which screen of the "display". */
352 Window parentWindow, /* Window ID of the parent window for
353 * the created window. */
354 int windowX, /* Desired X coord. of the window. */
355 int windowY, /* Desired Y coord of the window. */
356 int windowWidth, /* Desired width of the window. */
357 int windowHeight, /* Desired height of the window. */
358 int windowDepth, /* Desired depth of the window. */
359 Visual *pOverlayVisualToUse, /* The window's overlay planes visual.*/
360 int argc, /* Program's argc parameter. */
361 char *argv[], /* Program's argv parameter. */
362 char *windowName, /* Name to put on window's border. */
363 char *iconName, /* Name to put on window's icon. */
364 int transparentBackground, /* Non-zero if the window's background
365 * should be a transparent color. */
366 int *transparentColor, /* The transparent color to use as the
367 * window's background. */
368 Window *overlayWindow, /* Window ID of the created window. */
369 Colormap *overlayColormap, /* The window's colormap. */
370 int *mustFreeOverlayColormap/* Non-zero if the program must call
371 * XFreeColormap() for
372 * overlayColormap. */
373 );