wrlib/wraster.h

   1 /*
   2  * Raster graphics library
   3  *
   4  * Copyright (c) 1997-2003 Alfredo K. Kojima
   5  *
   6  *  This library is free software; you can redistribute it and/or
   7  *  modify it under the terms of the GNU Library General Public
   8  *  License as published by the Free Software Foundation; either
   9  *  version 2 of the License, or (at your option) any later version.
  10  *
  11  *  This library is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  *  Library General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU Library General Public
  17  *  License along with this library; if not, write to the Free
  18  *  Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
  19  *  MA 02110-1301, USA.
  20  */
  21
  22 /*
  23  * Environment variables:
  24  *
  25  * WRASTER_GAMMA <rgamma>/<ggamma>/<bgamma>
  26  * gamma correction value. Must be  greater than 0
  27  * Only for PseudoColor visuals.
  28  *
  29  * Default:
  30  * WRASTER_GAMMA 1/1/1
  31  *
  32  *
  33  * If you want a specific value for a screen, append the screen number
  34  * preceded by a hash to the variable name as in
  35  * WRASTER_GAMMA#1
  36  * for screen number 1
  37  */
  38
  39 #ifndef RLRASTER_H_
  40 #define RLRASTER_H_
  41
  42
  43 /* version of the header for the library */
  44 #define WRASTER_HEADER_VERSION  23
  45
  46
  47 #include <X11/Xlib.h>
  48 #include <X11/Xutil.h>
  49
  50 #ifdef USE_XSHM
  51 #include <X11/extensions/XShm.h>
  52 #endif
  53
  54
  55 /*
  56  * Define some macro to provide attributes for the compiler
  57  *
  58  * These attributes help producing better code and/or detecting bugs, however not all compiler support them
  59  * as they are not standard.
  60  * Because we're a public API header, we can't count on autoconf to detect them for us, so we use that #if
  61  * mechanism and define an internal macro appropriately. Please note that the macro are not considered being
  62  * part of the public API.
  63  */
  64 #if __GNUC__ >= 4
  65 #define __wrlib_deprecated(msg)  __attribute__ ((deprecated(msg)))
  66 #elif __GNUC__ >= 3
  67 #define __wrlib_deprecated(msg)  __attribute__ ((deprecated))
  68 #else
  69 #define __wrlib_deprecated(msg)
  70 #endif
  71
  72
  73 #ifdef __cplusplus
  74 extern "C" {
  75 #endif /* __cplusplus */
  76
  77 /* RBestMatchRendering or RDitheredRendering */
  78 #define RC_RenderMode           (1<<0)
  79
  80 /* number of colors per channel for colormap in PseudoColor mode */
  81 #define RC_ColorsPerChannel     (1<<1)
  82
  83 /* do gamma correction */
  84 #define RC_GammaCorrection      (1<<2)
  85
  86 /* visual id to use */
  87 #define RC_VisualID             (1<<3)
  88
  89 /* shared memory usage */
  90 #define RC_UseSharedMemory      (1<<4)
  91
  92 /* use default instead of best visual */
  93 #define RC_DefaultVisual        (1<<5)
  94
  95 /* filter type for smoothed scaling */
  96 #define RC_ScalingFilter        (1<<6)
  97
  98 /* standard colormap usage */
  99 #define RC_StandardColormap     (1<<7)
 100
 101
 102
 103 /* image display modes */
 104 typedef enum {
 105         RDitheredRendering = 0,
 106         RBestMatchRendering = 1
 107 } RRenderingMode;
 108
 109
 110 /* std colormap usage/creation modes */
 111 typedef enum {
 112         RUseStdColormap,        /* default: fallbacks to RIgnore if there is none defined */
 113         RCreateStdColormap,
 114         RIgnoreStdColormap
 115 } RStdColormapMode;
 116
 117
 118 /* smoothed scaling filter types */
 119 typedef enum {
 120         RBoxFilter,
 121         RTriangleFilter,
 122         RBellFilter,
 123         RBSplineFilter,
 124         RLanczos3Filter,
 125         RMitchellFilter
 126 } RScalingFilter;
 127
 128
 129 typedef struct RContextAttributes {
 130     int flags;
 131     RRenderingMode render_mode;
 132     int colors_per_channel;            /* for PseudoColor */
 133     float rgamma;                      /* gamma correction for red, */
 134     float ggamma;                      /* green, */
 135     float bgamma;                      /* and blue */
 136     VisualID visualid;         /* visual ID to use */
 137     int use_shared_memory;             /* True of False */
 138     RScalingFilter scaling_filter;
 139     RStdColormapMode standard_colormap_mode;    /* what to do with std cma */
 140 } RContextAttributes;
 141
 142
 143 /*
 144  * describes a screen in terms of depth, visual, number of colors
 145  * we can use, if we should do dithering, and what colors to use for
 146  * dithering.
 147  */
 148 typedef struct RContext {
 149     Display *dpy;
 150     int screen_number;
 151     Colormap cmap;
 152
 153     RContextAttributes *attribs;
 154
 155     GC copy_gc;
 156
 157     Visual *visual;
 158     int depth;
 159     Window drawable;               /* window to pass for XCreatePixmap().*/
 160     /* generally = root */
 161     int vclass;
 162
 163     unsigned long black;
 164     unsigned long white;
 165
 166     int red_offset;                    /* only used in 24bpp */
 167     int green_offset;
 168     int blue_offset;
 169
 170     /* only used for pseudocolor and grayscale */
 171
 172     XStandardColormap *std_rgb_map;    /* standard RGB colormap */
 173     XStandardColormap *std_gray_map;   /* standard grayscale colormap */
 174
 175     int ncolors;                       /* total number of colors we can use */
 176     XColor *colors;                    /* internal colormap */
 177     unsigned long *pixels;             /* RContext->colors[].pixel */
 178
 179     struct {
 180         unsigned int use_shared_pixmap:1;
 181         unsigned int optimize_for_speed:1
 182             __wrlib_deprecated("Flag optimize_for_speed in RContext is not used anymore "
 183                                "and will be removed in future version, please do not use");
 184     } flags;
 185 } RContext;
 186
 187
 188 typedef struct RColor {
 189     unsigned char red;
 190     unsigned char green;
 191     unsigned char blue;
 192     unsigned char alpha;
 193 } RColor;
 194
 195
 196 typedef struct RHSVColor {
 197     unsigned short hue;        /* 0-359 */
 198     unsigned char saturation;      /* 0-255 */
 199     unsigned char value;               /* 0-255 */
 200 } RHSVColor;
 201
 202
 203
 204 typedef struct RPoint {
 205     int x, y;
 206 } RPoint;
 207
 208
 209 typedef struct RSegment {
 210     int x1, y1, x2, y2;
 211 } RSegment;
 212
 213
 214
 215 /* image formats */
 216 enum RImageFormat {
 217     RRGBFormat,
 218     RRGBAFormat
 219 };
 220
 221
 222 /*
 223  * internal 24bit+alpha image representation
 224  */
 225 typedef struct RImage {
 226     unsigned char *data;       /* image data RGBA or RGB */
 227     int width, height;     /* size of the image */
 228     enum RImageFormat format;
 229     RColor background;     /* background color */
 230     int refCount;
 231 } RImage;
 232
 233
 234 /*
 235  * internal wrapper for XImage. Used for shm abstraction
 236  */
 237 typedef struct RXImage {
 238     XImage *image;
 239
 240     /* Private data. Do not access */
 241 #ifdef USE_XSHM
 242     XShmSegmentInfo info;
 243     char is_shared;
 244 #endif
 245 } RXImage;
 246
 247
 248 /* note that not all operations are supported in all functions */
 249 typedef enum {
 250     RClearOperation,           /* clear with 0 */
 251     RCopyOperation,
 252     RNormalOperation,          /* same as combine */
 253     RAddOperation,
 254     RSubtractOperation
 255 } RPixelOperation;
 256
 257
 258 typedef enum {
 259     RAbsoluteCoordinates = 0,
 260     RRelativeCoordinates = 1
 261 } RCoordinatesMode;
 262
 263
 264 enum {
 265     RSunkenBevel        = -1,
 266     RNoBevel    = 0,
 267     RRaisedBevel        = 1
 268 };
 269 /* bw compat */
 270 #define RBEV_SUNKEN     RSunkenBevel
 271 /* 1 pixel wide */
 272 #define RBEV_RAISED     RRaisedBevel
 273 /* 1 pixel wide on top/left 2 on bottom/right */
 274 #define RBEV_RAISED2    2
 275 /* 2 pixel width */
 276 #define RBEV_RAISED3    3
 277
 278 typedef enum {
 279     RHorizontalGradient = 2,
 280     RVerticalGradient = 3,
 281     RDiagonalGradient = 4
 282 } RGradientStyle;
 283 /* for backwards compatibility */
 284 #define RGRD_HORIZONTAL  RHorizontalGradient
 285 #define RGRD_VERTICAL   RVerticalGradient
 286 #define RGRD_DIAGONAL   RDiagonalGradient
 287
 288
 289 /*
 290  * How an image can be flipped, for RFlipImage
 291  *
 292  * Values are actually bit-mask which can be OR'd
 293  */
 294 #define RHorizontalFlip 0x0001
 295 #define RVerticalFlip   0x0002
 296
 297
 298 /* error codes */
 299 #define RERR_NONE               0
 300 #define RERR_OPEN               1      /* cant open file */
 301 #define RERR_READ               2      /* error reading from file */
 302 #define RERR_WRITE              3      /* error writing to file */
 303 #define RERR_NOMEMORY           4      /* out of memory */
 304 #define RERR_NOCOLOR            5      /* out of color cells */
 305 #define RERR_BADIMAGEFILE       6      /* image file is corrupted or invalid */
 306 #define RERR_BADFORMAT          7      /* image file format is unknown */
 307 #define RERR_BADINDEX           8      /* no such image index in file */
 308
 309 #define RERR_BADVISUALID        16     /* invalid visual ID requested for context */
 310 #define RERR_STDCMAPFAIL        17     /* failed to created std colormap */
 311
 312 #define RERR_XERROR             127    /* internal X error */
 313 #define RERR_INTERNAL           128    /* should not happen */
 314
 315
 316 /*
 317  * Cleaning before application exit
 318  */
 319 void RShutdown(void);
 320
 321 /*
 322  * Returns a NULL terminated array of strings containing the
 323  * supported formats, such as: TIFF, XPM, PNG, JPEG, PPM, GIF
 324  * Do not free the returned data.
 325  */
 326 char **RSupportedFileFormats(void);
 327
 328
 329 char *RGetImageFileFormat(const char *file);
 330
 331 /*
 332  * Xlib contexts
 333  */
 334 RContext *RCreateContext(Display *dpy, int screen_number,
 335                          const RContextAttributes *attribs);
 336
 337 void RDestroyContext(RContext *context);
 338
 339 Bool RGetClosestXColor(RContext *context, const RColor *color, XColor *retColor);
 340
 341 /*
 342  * RImage creation
 343  */
 344 RImage *RCreateImage(unsigned width, unsigned height, int alpha);
 345
 346 RImage *RCreateImageFromXImage(RContext *context, XImage *image, XImage *mask);
 347
 348 RImage *RCreateImageFromDrawable(RContext *context, Drawable drawable,
 349                                  Pixmap mask);
 350
 351 RImage *RLoadImage(RContext *context, const char *file, int index);
 352
 353 RImage* RRetainImage(RImage *image);
 354
 355 void RReleaseImage(RImage *image);
 356
 357 RImage *RGetImageFromXPMData(RContext *context, char **xpmData);
 358
 359 /*
 360  * RImage storing
 361  */
 362 Bool RSaveImage(RImage *image, const char *filename, const char *format);
 363
 364 /*
 365  * Area manipulation
 366  */
 367 RImage *RCloneImage(RImage *image);
 368
 369 RImage *RGetSubImage(RImage *image, int x, int y, unsigned width,
 370                      unsigned height);
 371
 372 void RCombineImageWithColor(RImage *image, const RColor *color);
 373
 374 void RCombineImages(RImage *image, RImage *src);
 375
 376 void RCombineArea(RImage *image, RImage *src, int sx, int sy, unsigned width,
 377                   unsigned height, int dx, int dy);
 378
 379 void RCopyArea(RImage *image, RImage *src, int sx, int sy, unsigned width,
 380                unsigned height, int dx, int dy);
 381
 382 void RCombineImagesWithOpaqueness(RImage *image, RImage *src, int opaqueness);
 383
 384 void RCombineAreaWithOpaqueness(RImage *image, RImage *src, int sx, int sy,
 385                                 unsigned width, unsigned height, int dx, int dy,
 386                                 int opaqueness);
 387
 388 void RCombineAlpha(unsigned char *d, unsigned char *s, int s_has_alpha,
 389                    int width, int height, int dwi, int swi, int opacity);
 390
 391 RImage *RScaleImage(RImage *image, unsigned new_width, unsigned new_height);
 392
 393 RImage *RSmoothScaleImage(RImage *src, unsigned new_width,
 394                           unsigned new_height);
 395
 396 RImage *RRotateImage(RImage *image, float angle);
 397
 398 RImage *RFlipImage(RImage *image, int mode);
 399
 400 RImage *RMakeTiledImage(RImage *tile, unsigned width, unsigned height);
 401
 402 RImage* RMakeCenteredImage(RImage *image, unsigned width, unsigned height,
 403                            const RColor *color);
 404
 405 /*
 406  * Drawing
 407  */
 408 Bool RGetPixel(RImage *image, int x, int y, RColor *color);
 409
 410 void RPutPixel(RImage *image, int x, int y, const RColor *color);
 411
 412 void ROperatePixel(RImage *image, RPixelOperation operation, int x, int y, const RColor *color);
 413
 414 void RPutPixels(RImage *image, const RPoint *points, int npoints, RCoordinatesMode mode,
 415                 const RColor *color);
 416
 417 void ROperatePixels(RImage *image, RPixelOperation operation, const RPoint *points,
 418                     int npoints, RCoordinatesMode mode, const RColor *color);
 419
 420 int RDrawLine(RImage *image, int x0, int y0, int x1, int y1, const RColor *color);
 421
 422 int ROperateLine(RImage *image, RPixelOperation operation, int x0, int y0, int x1, int y1,
 423                  const RColor *color);
 424
 425 void RDrawLines(RImage *image, const RPoint *points, int npoints, RCoordinatesMode mode,
 426                 const RColor *color);
 427
 428 void ROperateLines(RImage *image, RPixelOperation operation, const RPoint *points, int npoints,
 429                    RCoordinatesMode mode, const RColor *color);
 430
 431 void ROperateRectangle(RImage *image, RPixelOperation operation, int x0, int y0, int x1, int y1, const RColor *color);
 432
 433 void RDrawSegments(RImage *image, const RSegment *segs, int nsegs, const RColor *color);
 434
 435 void ROperateSegments(RImage *image, RPixelOperation operation, const RSegment *segs, int nsegs,
 436                       const RColor *color);
 437
 438 /*
 439  * Color convertion
 440  */
 441 void RRGBtoHSV(const RColor *color, RHSVColor *hsv);
 442 void RHSVtoRGB(const RHSVColor *hsv, RColor *rgb);
 443
 444 /*
 445  * Painting
 446  */
 447 void RClearImage(RImage *image, const RColor *color);
 448
 449 void RLightImage(RImage *image, const RColor *color);
 450
 451 void RFillImage(RImage *image, const RColor *color);
 452
 453 void RBevelImage(RImage *image, int bevel_type);
 454
 455 RImage *RRenderGradient(unsigned width, unsigned height, const RColor *from,
 456                         const RColor *to, RGradientStyle style);
 457
 458
 459 RImage *RRenderMultiGradient(unsigned width, unsigned height, RColor **colors,
 460                              RGradientStyle style);
 461
 462
 463 RImage *RRenderInterwovenGradient(unsigned width, unsigned height,
 464                                   RColor colors1[2], int thickness1,
 465                                   RColor colors2[2], int thickness2);
 466
 467
 468 /*
 469  * Convertion into X Pixmaps
 470  */
 471 int RConvertImage(RContext *context, RImage *image, Pixmap *pixmap);
 472
 473 int RConvertImageMask(RContext *context, RImage *image, Pixmap *pixmap,
 474                       Pixmap *mask, int threshold);
 475
 476
 477 /*
 478  * misc. utilities
 479  */
 480 RXImage *RCreateXImage(RContext *context, int depth,
 481                        unsigned width, unsigned height);
 482
 483 RXImage *RGetXImage(RContext *context, Drawable d, int x, int y,
 484                     unsigned width, unsigned height);
 485
 486 void RDestroyXImage(RContext *context, RXImage *ximage);
 487
 488 void RPutXImage(RContext *context, Drawable d, GC gc, RXImage *ximage,
 489                 int src_x, int src_y, int dest_x, int dest_y,
 490                 unsigned width, unsigned height);
 491
 492 /* do not free the returned string! */
 493 const char *RMessageForError(int errorCode);
 494
 495 int RBlurImage(RImage *image);
 496
 497 /****** Global Variables *******/
 498
 499 extern int RErrorCode;
 500
 501 #ifdef __cplusplus
 502 }
 503 #endif /* __cplusplus */
 504
 505 /*
 506  * The definitions below are done for internal use only
 507  * We undef them so users of the library may not misuse them
 508  */
 509 #undef __wrlib_deprecated
 510
 511 #endif