Debian Codegraph @

contrib/xwintoppm/wsutils.h

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