# Driver API

Header | cups/driver.h
--- | ---
Library | -lcupsdriver
See Also | Programming: Introduction to CUPS Programming

## Contents

- Overview
- Functions
  - cupsCMYKDelete
  - cupsCMYKDoBlack
  - cupsCMYKDoCMYK
  - cupsCMYKDoGray
  - cupsCMYKDoRGB
  - cupsCMYKLoad
  - cupsCMYKNew
  - cupsCMYKSetBlack
  - cupsCMYKSetCurve
  - cupsCMYKSetGamma
  - cupsCMYKSetInkLimit
  - cupsCMYKSetLtDk
  - cupsCheckBytes
  - cupsCheckValue
  - cupsDitherDelete
  - cupsDitherLine
  - cupsDitherNew
  - cupsFindAttr
  - cupsLutDelete
  - cupsLutLoad
  - cupsLutNew
  - cupsPackHorizontal
  - cupsPackHorizontal2
  - cupsPackHorizontalBit
  - cupsPackVertical
  - cupsRGBDelete
  - cupsRGBDoGray
  - cupsRGBDoRGB
  - cupsRGBLoad
  - cupsRGBNew
- Data Types
  - cups_cmyk_t
  - cups_dither_t
  - cups_lut_t
  - cups_rgb_t
  - cups_sample_t
- Structures
  - cups_cmyk_s
  - cups_dither_s
  - cups_lut_s
  - cups_rgb_s
  - cups_sample_s
- Variables
  - cups_scmy_lut[256]
  - cups_srgb_lut[256]

## Overview

The driver API provides common dithering, color conversion, and utility functions for CUPS drivers.

## Functions

### cupsCMYKDelete

Delete a color separation.

void cupsCMYKDelete (
cups_cmyk_t *cmyk
);

#### Parameters

cmyk
  Color separation

### cupsCMYKDoBlack

Do a black separation...

void cupsCMYKDoBlack (
const cups_cmyk_t *cmyk,
const unsigned char *input,
short *output,
int num_pixels
);

#### Parameters

cmyk
  Color separation
input
  Input grayscale pixels
output
  Output Device-N pixels
num_pixels
  Number of pixels

### cupsCMYKDoCMYK

Do a CMYK separation...

void cupsCMYKDoCMYK (
const cups_cmyk_t *cmyk,
const unsigned char *input,
short *output,
int num_pixels
);

#### Parameters

cmyk
  Color separation
input
  Input grayscale pixels
output
  Output Device-N pixels
num_pixels
  Number of pixels

### cupsCMYKDoGray

Do a grayscale separation...

void cupsCMYKDoGray (
const cups_cmyk_t *cmyk,
const unsigned char *input,
short *output,
int num_pixels
);

#### Parameters

cmyk
  Color separation
input
  Input grayscale pixels
output
  Output Device-N pixels
num_pixels
  Number of pixels

### cupsCMYKDoRGB

Do an sRGB separation...

void cupsCMYKDoRGB (
const cups_cmyk_t *cmyk,
const unsigned char *input,
short *output,
int num_pixels
);

#### Parameters

cmyk
  Color separation
input
  Input grayscale pixels
output
  Output Device-N pixels
num_pixels
  Number of pixels

### cupsCMYKLoad

Load a CMYK color profile from PPD attributes.

cups_cmyk_t *cupsCMYKLoad (
ppd_file_t *ppd,
const char *colormodel,
const char *media,
const char *resolution
);

#### Parameters

ppd
  PPD file
colormodel
  ColorModel value
media
  MediaType value
resolution
  Resolution value

#### Return Value

CMYK color separation

### cupsCMYKNew

Create a new CMYK color separation.

cups_cmyk_t *cupsCMYKNew (
int num_channels
);

#### Parameters

num_channels
  Number of color components

#### Return Value

New CMYK separation or NULL

### cupsCMYKSetBlack

Set the transition range for CMY to black.

void cupsCMYKSetBlack (
cups_cmyk_t *cmyk,
float lower,
float upper
);

#### Parameters

cmyk
  CMYK color separation
lower
  No black ink
upper
  Only black ink

### cupsCMYKSetCurve

Set a color transform curve using points.

void cupsCMYKSetCurve (
cups_cmyk_t *cmyk,
int channel,
int num_xypoints,
const float *xypoints
);

#### Parameters

cmyk
  CMYK color separation
channel
  Color channel
num_xypoints
  Number of X,Y points
xypoints
  X,Y points

### cupsCMYKSetGamma

Set a color transform curve using gamma and density.

void cupsCMYKSetGamma (
cups_cmyk_t *cmyk,
int channel,
float gamval,
float density
);

#### Parameters

cmyk
  CMYK color separation
channel
  Ink channel
gamval
  Gamma correction
density
  Maximum density

### cupsCMYKSetInkLimit

Set the limit on the amount of ink.

void cupsCMYKSetInkLimit (
cups_cmyk_t *cmyk,
float limit
);

#### Parameters

cmyk
  CMYK color separation
limit
  Limit of ink

### cupsCMYKSetLtDk

Set light/dark ink transforms.

void cupsCMYKSetLtDk (
cups_cmyk_t *cmyk,
int channel,
float light,
float dark
);

#### Parameters

cmyk
  CMYK color separation
channel
  Dark ink channel (+1 for light)
light
  Light ink only level
dark
  Dark ink only level

### cupsCheckBytes

Check to see if all bytes are zero.

int cupsCheckBytes (
const unsigned char *bytes,
int length
);

#### Parameters

bytes
  Bytes to check
length
  Number of bytes to check

#### Return Value

1 if they match

### cupsCheckValue

Check to see if all bytes match the given value.

int cupsCheckValue (
const unsigned char *bytes,
int length,
const unsigned char value
);

#### Parameters

bytes
  Bytes to check
length
  Number of bytes to check
value
  Value to check

#### Return Value

1 if they match

### cupsDitherDelete

Free a dithering buffer.

void cupsDitherDelete (
cups_dither_t *d
);

#### Parameters

d
  Dithering buffer

#### Discussion

Returns 0 on success, -1 on failure.

### cupsDitherLine

Dither a line of pixels...

void cupsDitherLine (
cups_dither_t *d,
const cups_lut_t *lut,
const short *data,
int num_channels,
unsigned char *p
);

#### Parameters

d
  Dither data
lut
  Lookup table
data
  Separation data
num_channels
  Number of components
p
  Pixels

### cupsDitherNew

Create an error-diffusion dithering buffer.

cups_dither_t *cupsDitherNew (
int width
);

#### Parameters

width
  Width of output in pixels

#### Return Value

New state array

### cupsFindAttr

Find a PPD attribute based on the colormodel, media, and resolution.

ppd_attr_t *cupsFindAttr (
ppd_file_t *ppd,
const char *name,
const char *colormodel,
const char *media,
const char *resolution,
char *spec,
int specsize
);

#### Parameters

ppd
  PPD file
name
  Attribute name
colormodel
  Color model
media
  Media type
resolution
  Resolution
spec
  Final selection string
specsize
  Size of string buffer

#### Return Value

Matching attribute or NULL

### cupsLutDelete

Free the memory used by a lookup table.

void cupsLutDelete (
cups_lut_t *lut
);

#### Parameters

lut
  Lookup table to free

### cupsLutLoad

Load a LUT from a PPD file.

cups_lut_t *cupsLutLoad (
ppd_file_t *ppd,
const char *colormodel,
const char *media,
const char *resolution,
const char *ink
);

#### Parameters

ppd
  PPD file
colormodel
  Color model
media
  Media type
resolution
  Resolution
ink
  Ink name

#### Return Value

New lookup table

### cupsLutNew

Make a lookup table from a list of pixel values.

cups_lut_t *cupsLutNew (
int num_values,
const float *values
);

#### Parameters

num_values
  Number of values
values
  Lookup table values

#### Return Value

New lookup table

#### Discussion

Returns a pointer to the lookup table on success, NULL on failure.

### cupsPackHorizontal

Pack pixels horizontally...

void cupsPackHorizontal (
const unsigned char *ipixels,
unsigned char *obytes,
int width,
const unsigned char clearto,
const int step
);

#### Parameters

ipixels
  Input pixels
obytes
  Output bytes
width
  Number of pixels
clearto
  Initial value of bytes
step
  Step value between pixels

### cupsPackHorizontal2

Pack 2-bit pixels horizontally...

void cupsPackHorizontal2 (
const unsigned char *ipixels,
unsigned char *obytes,
int width,
const int step
);

#### Parameters

ipixels
  Input pixels
obytes
  Output bytes
width
  Number of pixels
step
  Stepping value

### cupsPackHorizontalBit

Pack pixels horizontally by bit...

void cupsPackHorizontalBit (
const unsigned char *ipixels,
unsigned char *obytes,
int width,
const unsigned char clearto,
const unsigned char bit
);

#### Parameters

ipixels
  Input pixels
obytes
  Output bytes
width
  Number of pixels
clearto
  Initial value of bytes
bit
  Bit to check

### cupsPackVertical

Pack pixels vertically...

void cupsPackVertical (
const unsigned char *ipixels,
unsigned char *obytes,
int width,
const unsigned char bit,
const int step
);

#### Parameters

ipixels
  Input pixels
obytes
  Output bytes
width
  Number of input pixels
bit
  Output bit
step
  Number of bytes between columns

### cupsRGBDelete

Delete a color separation.

void cupsRGBDelete (
cups_rgb_t *rgbptr
);

#### Parameters

rgbptr
  Color separation

### cupsRGBDoGray

Do a grayscale separation...

void cupsRGBDoGray (
cups_rgb_t *rgbptr,
const unsigned char *input,
unsigned char *output,
int num_pixels
);

#### Parameters

rgbptr
  Color separation
input
  Input grayscale pixels
output
  Output Device-N pixels
num_pixels
  Number of pixels

### cupsRGBDoRGB

Do a RGB separation...

void cupsRGBDoRGB (
cups_rgb_t *rgbptr,
const unsigned char *input,
unsigned char *output,
int num_pixels
);

#### Parameters

rgbptr
  Color separation
input
  Input RGB pixels
output
  Output Device-N pixels
num_pixels
  Number of pixels

### cupsRGBLoad

Load a RGB color profile from a PPD file.

cups_rgb_t *cupsRGBLoad (
ppd_file_t *ppd,
const char *colormodel,
const char *media,
const char *resolution
);

#### Parameters

ppd
  PPD file
colormodel
  Color model
media
  Media type
resolution
  Resolution

#### Return Value

New color profile

### cupsRGBNew

Create a new RGB color separation.

cups_rgb_t *cupsRGBNew (
int num_samples,
cups_sample_t *samples,
int cube_size,
int num_channels
);

#### Parameters

num_samples
  Number of samples
samples
  Samples
cube_size
  Size of LUT cube
num_channels
  Number of color components

#### Return Value

New color separation or NULL

## Data Types

### cups_cmyk_t

Simple CMYK lookup table

typedef struct cups_cmyk_s cups_cmyk_t;

### cups_dither_t

Dithering State

typedef struct cups_dither_s cups_dither_t;

### cups_lut_t

Lookup Table for Dithering

typedef struct cups_lut_s cups_lut_t;

### cups_rgb_t

Color separation lookup table

typedef struct cups_rgb_s cups_rgb_t;

### cups_sample_t

Color sample point

typedef struct cups_sample_s cups_sample_t;

## Structures

### cups_cmyk_s

Simple CMYK lookup table

struct cups_cmyk_s {
unsigned char black_lut[256];
short *channels[CUPS_MAX_CHAN];
unsigned char color_lut[256];
int ink_limit;
int num_channels;
};

#### Members

black_lut[256]
  Black generation LUT
channels[CUPS_MAX_CHAN]
  Lookup tables
color_lut[256]
  Color removal LUT
ink_limit
  Ink limit
num_channels
  Number of components

### cups_dither_s

Dithering State

struct cups_dither_s {
int errors[96];
int row;
int width;
};

#### Members

errors[96]
  Error values
row
  Current row
width
  Width of buffer

### cups_lut_s

Lookup Table for Dithering

struct cups_lut_s {
int error;
short intensity;
short pixel;
};

#### Members

error
  Error from desired value
intensity
  Adjusted intensity
pixel
  Output pixel value

### cups_rgb_s

Color separation lookup table

struct cups_rgb_s {
unsigned char black[CUPS_MAX_RGB];
int cache_init;
unsigned char ****colors;
int cube_index[256];
int cube_mult[256];
int cube_size;
int num_channels;
unsigned char white[CUPS_MAX_RGB];
};

#### Members

black[CUPS_MAX_RGB]
  Cached black (sRGB = 0,0,0)
cache_init
  Are cached values initialized?
colors
  4-D array of sample values
cube_index[256]
  Index into cube for a given sRGB value
cube_mult[256]
  Multiplier value for a given sRGB value
cube_size
  Size of color cube (2-N) on a side
num_channels
  Number of colors per sample
white[CUPS_MAX_RGB]
  Cached white (sRGB = 255,255,255)

### cups_sample_s

Color sample point

struct cups_sample_s {
unsigned char colors[CUPS_MAX_RGB];
unsigned char rgb[3];
};

#### Members

colors[CUPS_MAX_RGB]
  Color values
rgb[3]
  sRGB values

## Variables

### cups_scmy_lut[256]

sRGB gamma lookup table (inverted)

extern const unsigned char cups_scmy_lut[256];

### cups_srgb_lut[256]

sRGB gamma lookup table

extern const unsigned char cups_srgb_lut[256];