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  24
  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 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)
  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 #if __GNUC__ >= 3
  73 /* Apparently introduced in GCC 3.0.x */
  74 /* Function returns newly allocated memory that does not alias any existing variable */
  75 #define __wrlib_nonalias         __attribute__ ((malloc))
  76 #else
  77 #define __wrlib_nonalias
  78 #endif
  79
  80 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3)
  81 /* Apparently introduced in GCC 3.3.x */
  82 /* The argument at index #i must not be NULL */
  83 #define __wrlib_nonnull(...)     __attribute__ ((nonnull(__VA_ARGS__)))
  84 #else
  85 #define __wrlib_nonnull(argidx)
  86 #endif
  87
  88 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
  89 /* Apparently introduced in GCC 3.4.x */
  90 /* The return value of this function *must* be checked/used */
  91 #define __wrlib_useresult        __attribute__ ((warn_unused_result))
  92 #else
  93 #define __wrlib_useresult
  94 #endif
  95
  96
  97 #ifdef __cplusplus
  98 extern "C" {
  99 #endif /* __cplusplus */
 100
 101 /* RBestMatchRendering or RDitheredRendering */
 102 #define RC_RenderMode           (1<<0)
 103
 104 /* number of colors per channel for colormap in PseudoColor mode */
 105 #define RC_ColorsPerChannel     (1<<1)
 106
 107 /* do gamma correction */
 108 #define RC_GammaCorrection      (1<<2)
 109
 110 /* visual id to use */
 111 #define RC_VisualID             (1<<3)
 112
 113 /* shared memory usage */
 114 #define RC_UseSharedMemory      (1<<4)
 115
 116 /* use default instead of best visual */
 117 #define RC_DefaultVisual        (1<<5)
 118
 119 /* filter type for smoothed scaling */
 120 #define RC_ScalingFilter        (1<<6)
 121
 122 /* standard colormap usage */
 123 #define RC_StandardColormap     (1<<7)
 124
 125
 126
 127 /* image display modes */
 128 typedef enum {
 129         RDitheredRendering = 0,
 130         RBestMatchRendering = 1
 131 } RRenderingMode;
 132
 133
 134 /* std colormap usage/creation modes */
 135 typedef enum {
 136         RUseStdColormap,        /* default: fallbacks to RIgnore if there is none defined */
 137         RCreateStdColormap,
 138         RIgnoreStdColormap
 139 } RStdColormapMode;
 140
 141
 142 /* smoothed scaling filter types */
 143 typedef enum {
 144         RBoxFilter,
 145         RTriangleFilter,
 146         RBellFilter,
 147         RBSplineFilter,
 148         RLanczos3Filter,
 149         RMitchellFilter
 150 } RScalingFilter;
 151
 152
 153 typedef struct RContextAttributes {
 154     int flags;
 155     RRenderingMode render_mode;
 156     int colors_per_channel;            /* for PseudoColor */
 157     float rgamma;                      /* gamma correction for red, */
 158     float ggamma;                      /* green, */
 159     float bgamma;                      /* and blue */
 160     VisualID visualid;         /* visual ID to use */
 161     int use_shared_memory;             /* True of False */
 162     RScalingFilter scaling_filter;
 163     RStdColormapMode standard_colormap_mode;    /* what to do with std cma */
 164 } RContextAttributes;
 165
 166
 167 /*
 168  * describes a screen in terms of depth, visual, number of colors
 169  * we can use, if we should do dithering, and what colors to use for
 170  * dithering.
 171  */
 172 typedef struct RContext {
 173     Display *dpy;
 174     int screen_number;
 175     Colormap cmap;
 176
 177     RContextAttributes *attribs;
 178
 179     GC copy_gc;
 180
 181     Visual *visual;
 182     int depth;
 183     Window drawable;               /* window to pass for XCreatePixmap().*/
 184     /* generally = root */
 185     int vclass;
 186
 187     unsigned long black;
 188     unsigned long white;
 189
 190     int red_offset;                    /* only used in 24bpp */
 191     int green_offset;
 192     int blue_offset;
 193
 194     /* only used for pseudocolor and grayscale */
 195
 196     XStandardColormap *std_rgb_map;    /* standard RGB colormap */
 197     XStandardColormap *std_gray_map;   /* standard grayscale colormap */
 198
 199     int ncolors;                       /* total number of colors we can use */
 200     XColor *colors;                    /* internal colormap */
 201     unsigned long *pixels;             /* RContext->colors[].pixel */
 202
 203     struct {
 204         unsigned int use_shared_pixmap:1;
 205         unsigned int optimize_for_speed:1
 206             __wrlib_deprecated("Flag optimize_for_speed in RContext is not used anymore "
 207                                "and will be removed in future version, please do not use");
 208     } flags;
 209 } RContext;
 210
 211
 212 typedef struct RColor {
 213     unsigned char red;
 214     unsigned char green;
 215     unsigned char blue;
 216     unsigned char alpha;
 217 } RColor;
 218
 219
 220 typedef struct RHSVColor {
 221     unsigned short hue;        /* 0-359 */
 222     unsigned char saturation;      /* 0-255 */
 223     unsigned char value;               /* 0-255 */
 224 } RHSVColor;
 225
 226
 227
 228 typedef struct RPoint {
 229     int x, y;
 230 } RPoint;
 231
 232
 233 typedef struct RSegment {
 234     int x1, y1, x2, y2;
 235 } RSegment;
 236
 237
 238
 239 /* image formats */
 240 enum RImageFormat {
 241     RRGBFormat,
 242     RRGBAFormat
 243 };
 244
 245
 246 /*
 247  * internal 24bit+alpha image representation
 248  */
 249 typedef struct RImage {
 250     unsigned char *data;       /* image data RGBA or RGB */
 251     int width, height;     /* size of the image */
 252     enum RImageFormat format;
 253     RColor background;     /* background color */
 254     int refCount;
 255 } RImage;
 256
 257
 258 /*
 259  * internal wrapper for XImage. Used for shm abstraction
 260  */
 261 typedef struct RXImage {
 262     XImage *image;
 263
 264     /* Private data. Do not access */
 265 #ifdef USE_XSHM
 266     XShmSegmentInfo info;
 267     char is_shared;
 268 #endif
 269 } RXImage;
 270
 271
 272 /* note that not all operations are supported in all functions */
 273 typedef enum {
 274     RClearOperation,           /* clear with 0 */
 275     RCopyOperation,
 276     RNormalOperation,          /* same as combine */
 277     RAddOperation,
 278     RSubtractOperation
 279 } RPixelOperation;
 280
 281
 282 typedef enum {
 283     RAbsoluteCoordinates = 0,
 284     RRelativeCoordinates = 1
 285 } RCoordinatesMode;
 286
 287
 288 enum {
 289     RSunkenBevel        = -1,
 290     RNoBevel    = 0,
 291     RRaisedBevel        = 1
 292 };
 293 /* bw compat */
 294 #define RBEV_SUNKEN     RSunkenBevel
 295 /* 1 pixel wide */
 296 #define RBEV_RAISED     RRaisedBevel
 297 /* 1 pixel wide on top/left 2 on bottom/right */
 298 #define RBEV_RAISED2    2
 299 /* 2 pixel width */
 300 #define RBEV_RAISED3    3
 301
 302 typedef enum {
 303     RHorizontalGradient = 2,
 304     RVerticalGradient = 3,
 305     RDiagonalGradient = 4
 306 } RGradientStyle;
 307 /* for backwards compatibility */
 308 #define RGRD_HORIZONTAL  RHorizontalGradient
 309 #define RGRD_VERTICAL   RVerticalGradient
 310 #define RGRD_DIAGONAL   RDiagonalGradient
 311
 312
 313 /*
 314  * How an image can be flipped, for RFlipImage
 315  *
 316  * Values are actually bit-mask which can be OR'd
 317  */
 318 #define RHorizontalFlip 0x0001
 319 #define RVerticalFlip   0x0002
 320
 321
 322 /* error codes */
 323 #define RERR_NONE               0
 324 #define RERR_OPEN               1      /* cant open file */
 325 #define RERR_READ               2      /* error reading from file */
 326 #define RERR_WRITE              3      /* error writing to file */
 327 #define RERR_NOMEMORY           4      /* out of memory */
 328 #define RERR_NOCOLOR            5      /* out of color cells */
 329 #define RERR_BADIMAGEFILE       6      /* image file is corrupted or invalid */
 330 #define RERR_BADFORMAT          7      /* image file format is unknown */
 331 #define RERR_BADINDEX           8      /* no such image index in file */
 332
 333 #define RERR_BADVISUALID        16     /* invalid visual ID requested for context */
 334 #define RERR_STDCMAPFAIL        17     /* failed to created std colormap */
 335
 336 #define RERR_XERROR             127    /* internal X error */
 337 #define RERR_INTERNAL           128    /* should not happen */
 338
 339
 340 /*
 341  * Cleaning before application exit
 342  */
 343 void RShutdown(void);
 344
 345 /*
 346  * Returns a NULL terminated array of strings containing the
 347  * supported formats, such as: TIFF, XPM, PNG, JPEG, PPM, GIF
 348  * Do not free the returned data.
 349  */
 350 char **RSupportedFileFormats(void)
 351         __wrlib_useresult;
 352
 353
 354 char *RGetImageFileFormat(const char *file)
 355         __wrlib_useresult __wrlib_nonnull(1);
 356
 357 /*
 358  * Xlib contexts
 359  */
 360 RContext *RCreateContext(Display *dpy, int screen_number,
 361                          const RContextAttributes *attribs)
 362         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1);
 363
 364 void RDestroyContext(RContext *context);
 365
 366 Bool RGetClosestXColor(RContext *context, const RColor *color, XColor *retColor)
 367         __wrlib_nonnull(1, 2, 3);
 368
 369 /*
 370  * RImage creation
 371  */
 372 RImage *RCreateImage(unsigned width, unsigned height, int alpha)
 373         __wrlib_useresult __wrlib_nonalias;
 374
 375 RImage *RCreateImageFromXImage(RContext *context, XImage *image, XImage *mask)
 376         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1, 2);
 377
 378 RImage *RCreateImageFromDrawable(RContext *context, Drawable drawable,
 379                                  Pixmap mask)
 380         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1);
 381
 382 RImage *RLoadImage(RContext *context, const char *file, int index)
 383         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1, 2);
 384
 385 RImage* RRetainImage(RImage *image);
 386
 387 void RReleaseImage(RImage *image)
 388         __wrlib_nonnull(1);
 389
 390 RImage *RGetImageFromXPMData(RContext *context, char **xpmData)
 391         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1, 2);
 392
 393 /*
 394  * RImage storing
 395  */
 396 Bool RSaveImage(RImage *image, const char *filename, const char *format)
 397         __wrlib_nonnull(1, 2, 3);
 398
 399 /*
 400  * Area manipulation
 401  */
 402 RImage *RCloneImage(RImage *image)
 403         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1);
 404
 405 RImage *RGetSubImage(RImage *image, int x, int y, unsigned width,
 406                      unsigned height)
 407         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1);
 408
 409 void RCombineImageWithColor(RImage *image, const RColor *color)
 410         __wrlib_nonnull(1, 2);
 411
 412 void RCombineImages(RImage *image, RImage *src)
 413         __wrlib_nonnull(1, 2);
 414
 415 void RCombineArea(RImage *image, RImage *src, int sx, int sy, unsigned width,
 416                   unsigned height, int dx, int dy)
 417         __wrlib_nonnull(1, 2);
 418
 419 void RCopyArea(RImage *image, RImage *src, int sx, int sy, unsigned width,
 420                unsigned height, int dx, int dy)
 421         __wrlib_nonnull(1, 2);
 422
 423 void RCombineImagesWithOpaqueness(RImage *image, RImage *src, int opaqueness)
 424         __wrlib_nonnull(1, 2);
 425
 426 void RCombineAreaWithOpaqueness(RImage *image, RImage *src, int sx, int sy,
 427                                 unsigned width, unsigned height, int dx, int dy,
 428                                 int opaqueness)
 429         __wrlib_nonnull(1, 2);
 430
 431 void RCombineAlpha(unsigned char *d, unsigned char *s, int s_has_alpha,
 432                    int width, int height, int dwi, int swi, int opacity)
 433         __wrlib_nonnull(1, 2);
 434
 435 RImage *RScaleImage(RImage *image, unsigned new_width, unsigned new_height)
 436         __wrlib_useresult __wrlib_nonalias;
 437
 438 RImage *RSmoothScaleImage(RImage *src, unsigned new_width,
 439                           unsigned new_height)
 440         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1);
 441
 442 RImage *RRotateImage(RImage *image, float angle)
 443         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1);
 444
 445 RImage *RFlipImage(RImage *image, int mode)
 446         __wrlib_useresult __wrlib_nonalias;
 447
 448 RImage *RMakeTiledImage(RImage *tile, unsigned width, unsigned height)
 449         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1);
 450
 451 RImage* RMakeCenteredImage(RImage *image, unsigned width, unsigned height,
 452                            const RColor *color)
 453         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1, 4);
 454
 455 /*
 456  * Drawing
 457  */
 458 Bool RGetPixel(RImage *image, int x, int y, RColor *color)
 459         __wrlib_nonnull(1, 4);
 460
 461 void RPutPixel(RImage *image, int x, int y, const RColor *color)
 462         __wrlib_nonnull(1, 4);
 463
 464 void ROperatePixel(RImage *image, RPixelOperation operation, int x, int y, const RColor *color)
 465         __wrlib_nonnull(1, 5);
 466
 467 void RPutPixels(RImage *image, const RPoint *points, int npoints, RCoordinatesMode mode,
 468                 const RColor *color)
 469         __wrlib_nonnull(1, 2, 5);
 470
 471 void ROperatePixels(RImage *image, RPixelOperation operation, const RPoint *points,
 472                     int npoints, RCoordinatesMode mode, const RColor *color)
 473         __wrlib_nonnull(1, 3, 6);
 474
 475 int RDrawLine(RImage *image, int x0, int y0, int x1, int y1, const RColor *color)
 476         __wrlib_nonnull(1, 6);
 477
 478 int ROperateLine(RImage *image, RPixelOperation operation, int x0, int y0, int x1, int y1,
 479                  const RColor *color)
 480         __wrlib_nonnull(1, 7);
 481
 482 void RDrawLines(RImage *image, const RPoint *points, int npoints, RCoordinatesMode mode,
 483                 const RColor *color)
 484         __wrlib_nonnull(1, 2, 5);
 485
 486 void ROperateLines(RImage *image, RPixelOperation operation, const RPoint *points, int npoints,
 487                    RCoordinatesMode mode, const RColor *color)
 488         __wrlib_nonnull(1, 3, 6);
 489
 490 void ROperateRectangle(RImage *image, RPixelOperation operation, int x0, int y0, int x1, int y1, const RColor *color)
 491         __wrlib_nonnull(1, 7);
 492
 493 void RDrawSegments(RImage *image, const RSegment *segs, int nsegs, const RColor *color)
 494         __wrlib_nonnull(1, 2, 4);
 495
 496 void ROperateSegments(RImage *image, RPixelOperation operation, const RSegment *segs, int nsegs,
 497                       const RColor *color)
 498         __wrlib_nonnull(1, 3, 5);
 499
 500 /*
 501  * Color convertion
 502  */
 503 void RRGBtoHSV(const RColor *color, RHSVColor *hsv)
 504         __wrlib_nonnull(1, 2);
 505
 506 void RHSVtoRGB(const RHSVColor *hsv, RColor *rgb)
 507         __wrlib_nonnull(1, 2);
 508
 509 /*
 510  * Painting
 511  */
 512 void RClearImage(RImage *image, const RColor *color)
 513         __wrlib_nonnull(1, 2);
 514
 515 void RLightImage(RImage *image, const RColor *color)
 516         __wrlib_nonnull(1, 2);
 517
 518 void RFillImage(RImage *image, const RColor *color)
 519         __wrlib_nonnull(1, 2);
 520
 521 void RBevelImage(RImage *image, int bevel_type)
 522         __wrlib_nonnull(1);
 523
 524 RImage *RRenderGradient(unsigned width, unsigned height, const RColor *from,
 525                         const RColor *to, RGradientStyle style)
 526         __wrlib_nonalias __wrlib_useresult __wrlib_nonnull(3, 4);
 527
 528
 529 RImage *RRenderMultiGradient(unsigned width, unsigned height, RColor **colors,
 530                              RGradientStyle style)
 531         __wrlib_nonalias __wrlib_useresult __wrlib_nonnull(3);
 532
 533
 534 RImage *RRenderInterwovenGradient(unsigned width, unsigned height,
 535                                   RColor colors1[2], int thickness1,
 536                                   RColor colors2[2], int thickness2)
 537         __wrlib_nonalias __wrlib_useresult;
 538
 539
 540 /*
 541  * Convertion into X Pixmaps
 542  */
 543 int RConvertImage(RContext *context, RImage *image, Pixmap *pixmap)
 544         __wrlib_nonnull(1, 2, 3);
 545
 546 int RConvertImageMask(RContext *context, RImage *image, Pixmap *pixmap,
 547                       Pixmap *mask, int threshold)
 548         __wrlib_nonnull(1, 2, 3, 4);
 549
 550
 551 /*
 552  * misc. utilities
 553  */
 554 RXImage *RCreateXImage(RContext *context, int depth,
 555                        unsigned width, unsigned height)
 556         __wrlib_nonalias __wrlib_useresult __wrlib_nonnull(1);
 557
 558 RXImage *RGetXImage(RContext *context, Drawable d, int x, int y,
 559                     unsigned width, unsigned height)
 560         __wrlib_nonalias __wrlib_useresult __wrlib_nonnull(1);
 561
 562 void RDestroyXImage(RContext *context, RXImage *ximage)
 563         __wrlib_nonnull(1, 2);
 564
 565 void RPutXImage(RContext *context, Drawable d, GC gc, RXImage *ximage,
 566                 int src_x, int src_y, int dest_x, int dest_y,
 567                 unsigned width, unsigned height)
 568         __wrlib_nonnull(1, 3);
 569
 570 /* do not free the returned string! */
 571 const char *RMessageForError(int errorCode)
 572         __wrlib_useresult;
 573
 574 int RBlurImage(RImage *image)
 575         __wrlib_nonnull(1);
 576
 577 /****** Global Variables *******/
 578
 579 extern int RErrorCode;
 580
 581 #ifdef __cplusplus
 582 }
 583 #endif /* __cplusplus */
 584
 585 /*
 586  * The definitions below are done for internal use only
 587  * We undef them so users of the library may not misuse them
 588  */
 589 #undef __wrlib_deprecated
 590 #undef __wrlib_nonalias
 591 #undef __wrlib_nonnull
 592 #undef __wrlib_useresult
 593
 594 #endif