MuPDF X.Y.Z

fitz/color.h

Index

typedef

struct

enum

macro

global

function

Color

typedef fz_icc_profile

typedef struct fz_icc_profile fz_icc_profile

Opaque type for an ICC Profile.

typedef fz_colorspace

typedef struct fz_colorspace fz_colorspace

Describes a given colorspace.

typedef fz_pixmap

typedef struct fz_pixmap fz_pixmap

Pixmaps represent a set of pixels for a 2 dimensional region of a plane. Each pixel has n components per pixel. The components are in the order process-components, spot-colors, alpha, where there can be 0 of any of those types. The data is in premultiplied alpha when rendering, but non-premultiplied for colorspace conversions and rescaling.

enum fz_rendering_intent

enum fz_rendering_intent
{
        /* Same order as needed by lcms */
        FZ_RI_PERCEPTUAL,
        FZ_RI_RELATIVE_COLORIMETRIC,
        FZ_RI_SATURATION,
        FZ_RI_ABSOLUTE_COLORIMETRIC,
}

Color handling parameters: rendering intent, overprint, etc.

struct fz_color_params

struct fz_color_params
{
        uint8_t ri;     /* rendering intent */
        uint8_t bp;     /* black point compensation */
        uint8_t op;     /* overprinting */
        uint8_t opm;    /* overprint mode */
}

global fz_default_color_params

extern const fz_color_params fz_default_color_params

function fz_lookup_rendering_intent

int
fz_lookup_rendering_intent (
        const char *name
)

Map from (case sensitive) rendering intent string to enumeration value.

function fz_rendering_intent_name

const char *
fz_rendering_intent_name (
        int ri
)

Map from enumerated rendering intent to string.

The returned string is static and therefore must not be freed.

macro FZ_MAX_COLORS

#define FZ_MAX_COLORS 32

The maximum number of colorants available in any given color/colorspace (not including alpha).

Changing this value will alter the amount of memory being used (both stack and heap space), but not hugely. Speed should (largely) be determined by the number of colors actually used.

macro FZ_MAX_SAMPLES

#define FZ_MAX_SAMPLES (1 << 30)

The maximum number of samples allowed in any given image.

This limit is checked when allocating images.

enum fz_colorspace_type

enum fz_colorspace_type
{
        FZ_COLORSPACE_NONE,
        FZ_COLORSPACE_GRAY,
        FZ_COLORSPACE_RGB,
        FZ_COLORSPACE_BGR,
        FZ_COLORSPACE_CMYK,
        FZ_COLORSPACE_LAB,
        FZ_COLORSPACE_INDEXED,
        FZ_COLORSPACE_SEPARATION,
}

enum fz_colorspace_flags

enum fz_colorspace_flags
{
        FZ_COLORSPACE_IS_DEVICE = 1,
        FZ_COLORSPACE_IS_ICC = 2,
        FZ_COLORSPACE_HAS_CMYK = 4,
        FZ_COLORSPACE_HAS_SPOTS = 8,
        FZ_COLORSPACE_HAS_CMYK_AND_SPOTS = 4|8,
}

Constructors

function fz_new_colorspace

fz_colorspace *
fz_new_colorspace (
        fz_context *ctx,
        enum fz_colorspace_type type,
        int flags,
        int n,
        const char *name
)

Creates a new colorspace instance and returns a reference.

No internal checking is done that the colorspace type (e.g. CMYK) matches with the flags (e.g. FZ_COLORSPACE_HAS_CMYK) or colorant count (n) or name.

The reference should be dropped when it is finished with.

Colorspaces are immutable once created (with the exception of setting up colorant names for separation spaces).

function fz_keep_colorspace

fz_colorspace *
fz_keep_colorspace (
        fz_context *ctx,
        fz_colorspace *colorspace
)

Increment the reference count for the colorspace.

Returns the same pointer. Never throws an exception.

function fz_drop_colorspace

void
fz_drop_colorspace (
        fz_context *ctx,
        fz_colorspace *colorspace
)

Drops a reference to the colorspace.

When the reference count reaches zero, the colorspace is destroyed.

function fz_new_indexed_colorspace

fz_colorspace *
fz_new_indexed_colorspace (
        fz_context *ctx,
        fz_colorspace *base,
        int high,
        unsigned char *lookup
)

Create an indexed colorspace.

The supplied lookup table is high palette entries long. Each entry is n bytes long, where n is given by the number of colorants in the base colorspace, one byte per colorant.

Ownership of lookup is passed it; it will be freed on destruction, so must be heap allocated.

The colorspace will keep an additional reference to the base colorspace that will be dropped on destruction.

The returned reference should be dropped when it is finished with.

Colorspaces are immutable once created.

function fz_new_icc_colorspace

fz_colorspace *
fz_new_icc_colorspace (
        fz_context *ctx,
        enum fz_colorspace_type type,
        int flags,
        const char *name,
        fz_buffer *buf
)

Create a colorspace from an ICC profile supplied in buf.

Limited checking is done to ensure that the colorspace type is appropriate for the supplied ICC profile.

An additional reference is taken to buf, which will be dropped on destruction. Ownership is NOT passed in.

The returned reference should be dropped when it is finished with.

Colorspaces are immutable once created.

function fz_new_cal_gray_colorspace

fz_colorspace *
fz_new_cal_gray_colorspace (
        fz_context *ctx,
        float wp[3],
        float bp[3],
        float gamma
)

Create a calibrated gray colorspace.

The returned reference should be dropped when it is finished with.

Colorspaces are immutable once created.

function fz_new_cal_rgb_colorspace

fz_colorspace *
fz_new_cal_rgb_colorspace (
        fz_context *ctx,
        float wp[3],
        float bp[3],
        float gamma[3],
        float matrix[9]
)

Create a calibrated rgb colorspace.

The returned reference should be dropped when it is finished with.

Colorspaces are immutable once created.

function fz_colorspace_name_colorant

void
fz_colorspace_name_colorant (
        fz_context *ctx,
        fz_colorspace *cs,
        int n,
        const char *name
)

Assign a name for a given colorant in a colorspace.

Used while initially setting up a colorspace. The string is copied into local storage, so need not be retained by the caller.

function fz_colorspace_colorant

const char *
fz_colorspace_colorant (
        fz_context *ctx,
        fz_colorspace *cs,
        int n
)

Retrieve a the name for a colorant.

Returns a pointer with the same lifespan as the colorspace.

Colorspace properties

function fz_colorspace_digest

void
fz_colorspace_digest (
        fz_context *ctx,
        fz_colorspace *cs,
        unsigned char digest[16]
)

Get checksum of underlying ICC profile.

function fz_base_colorspace

fz_colorspace *
fz_base_colorspace (
        fz_context *ctx,
        fz_colorspace *cs
)

Get the ‘base’ colorspace for a colorspace.

For indexed colorspaces, this is the colorspace the index decodes into. For all other colorspaces, it is the colorspace itself.

The returned colorspace is ‘borrowed’ (i.e. no additional references are taken or dropped).

function fz_colorspace_type

enum fz_colorspace_type
fz_colorspace_type (
        fz_context *ctx,
        fz_colorspace *cs
)

Query the type of colorspace.

function fz_colorspace_name

const char *
fz_colorspace_name (
        fz_context *ctx,
        fz_colorspace *cs
)

Query the name of a colorspace.

The returned string has the same lifespan as the colorspace does. Caller should not free it.

function fz_colorspace_n

int
fz_colorspace_n (
        fz_context *ctx,
        fz_colorspace *cs
)

Query the number of colorants in a colorspace.

function fz_colorspace_is_subtractive

int
fz_colorspace_is_subtractive (
        fz_context *ctx,
        fz_colorspace *cs
)

True for CMYK, Separation and DeviceN colorspaces.

function fz_colorspace_device_n_has_only_cmyk

int
fz_colorspace_device_n_has_only_cmyk (
        fz_context *ctx,
        fz_colorspace *cs
)

True if DeviceN color space has only colorants from the CMYK set.

function fz_colorspace_device_n_has_cmyk

int
fz_colorspace_device_n_has_cmyk (
        fz_context *ctx,
        fz_colorspace *cs
)

True if DeviceN color space has cyan magenta yellow or black as one of its colorants.

Tests for particular types of colorspaces

function fz_colorspace_is_gray

int
fz_colorspace_is_gray (
        fz_context *ctx,
        fz_colorspace *cs
)

function fz_colorspace_is_rgb

int
fz_colorspace_is_rgb (
        fz_context *ctx,
        fz_colorspace *cs
)

function fz_colorspace_is_cmyk

int
fz_colorspace_is_cmyk (
        fz_context *ctx,
        fz_colorspace *cs
)

function fz_colorspace_is_lab

int
fz_colorspace_is_lab (
        fz_context *ctx,
        fz_colorspace *cs
)

function fz_colorspace_is_indexed

int
fz_colorspace_is_indexed (
        fz_context *ctx,
        fz_colorspace *cs
)

function fz_colorspace_is_icc

int
fz_colorspace_is_icc (
        fz_context *ctx,
        fz_colorspace *cs
)

function fz_colorspace_is_device_n

int
fz_colorspace_is_device_n (
        fz_context *ctx,
        fz_colorspace *cs
)

function fz_colorspace_is_device

int
fz_colorspace_is_device (
        fz_context *ctx,
        fz_colorspace *cs
)

function fz_colorspace_is_device_gray

int
fz_colorspace_is_device_gray (
        fz_context *ctx,
        fz_colorspace *cs
)

function fz_colorspace_is_device_cmyk

int
fz_colorspace_is_device_cmyk (
        fz_context *ctx,
        fz_colorspace *cs
)

function fz_colorspace_is_lab_icc

int
fz_colorspace_is_lab_icc (
        fz_context *ctx,
        fz_colorspace *cs
)

function fz_is_valid_blend_colorspace

int
fz_is_valid_blend_colorspace (
        fz_context *ctx,
        fz_colorspace *cs
)

Check to see that a colorspace is appropriate to be used as a blending space (i.e. only grey, rgb or cmyk).

Color conversion

function fz_clamp_color

void
fz_clamp_color (
        fz_context *ctx,
        fz_colorspace *cs,
        const float *in,
        float *out
)

Clamp the samples in a color to the correct ranges for a given colorspace.

function fz_convert_color

void
fz_convert_color (
        fz_context *ctx,
        fz_colorspace *ss,
        const float *sv,
        fz_colorspace *ds,
        float *dv,
        fz_colorspace *is,
        fz_color_params params
)

Convert color values sv from colorspace ss into colorvalues dv for colorspace ds, via an optional intervening space is, respecting the given color_params.

Global colorspaces

Retrieve global default colorspaces.

These return borrowed references that should not be dropped, unless they are kept first.

function fz_device_gray

fz_colorspace *
fz_device_gray (
        fz_context *ctx
)

function fz_device_rgb

fz_colorspace *
fz_device_rgb (
        fz_context *ctx
)

function fz_device_bgr

fz_colorspace *
fz_device_bgr (
        fz_context *ctx
)

function fz_device_cmyk

fz_colorspace *
fz_device_cmyk (
        fz_context *ctx
)

function fz_device_lab

fz_colorspace *
fz_device_lab (
        fz_context *ctx
)

Default (fallback) colorspace handling

struct fz_default_colorspaces

struct fz_default_colorspaces
{
        int refs;
        fz_colorspace *gray;
        fz_colorspace *rgb;
        fz_colorspace *cmyk;
        fz_colorspace *oi;
}  fz_default_colorspaces

Structure to hold default colorspaces.

function fz_new_default_colorspaces

fz_default_colorspaces *
fz_new_default_colorspaces (
        fz_context *ctx
)

Create a new default colorspace structure with values inherited from the context, and return a reference to it.

These can be overridden using fz_set_default_xxxx.

These should not be overridden while more than one caller has the reference for fear of race conditions.

The caller should drop this reference once finished with it.

function fz_keep_default_colorspaces

fz_default_colorspaces *
fz_keep_default_colorspaces (
        fz_context *ctx,
        fz_default_colorspaces *default_cs
)

Keep an additional reference to the default colorspaces structure.

Never throws exceptions.

function fz_drop_default_colorspaces

void
fz_drop_default_colorspaces (
        fz_context *ctx,
        fz_default_colorspaces *default_cs
)

Drop a reference to the default colorspaces structure. When the reference count reaches 0, the references it holds internally to the underlying colorspaces will be dropped, and the structure will be destroyed.

Never throws exceptions.

function fz_clone_default_colorspaces

fz_default_colorspaces *
fz_clone_default_colorspaces (
        fz_context *ctx,
        fz_default_colorspaces *base
)

Returns a reference to a newly cloned default colorspaces structure.

The new clone may safely be altered without fear of race conditions as the caller is the only reference holder.

function fz_default_gray

fz_colorspace *
fz_default_gray (
        fz_context *ctx,
        const fz_default_colorspaces *default_cs
)

Retrieve default colorspaces (typically page local).

If default_cs is non NULL, the default is retrieved from there, otherwise the global default is retrieved.

These return borrowed references that should not be dropped, unless they are kept first.

function fz_default_rgb

fz_colorspace *
fz_default_rgb (
        fz_context *ctx,
        const fz_default_colorspaces *default_cs
)

function fz_default_cmyk

fz_colorspace *
fz_default_cmyk (
        fz_context *ctx,
        const fz_default_colorspaces *default_cs
)

function fz_default_output_intent

fz_colorspace *
fz_default_output_intent (
        fz_context *ctx,
        const fz_default_colorspaces *default_cs
)

function fz_set_default_gray

void
fz_set_default_gray (
        fz_context *ctx,
        fz_default_colorspaces *default_cs,
        fz_colorspace *cs
)

Set new defaults within the default colorspace structure.

New references are taken to the new default, and references to the old defaults dropped.

Never throws exceptions.

function fz_set_default_rgb

void
fz_set_default_rgb (
        fz_context *ctx,
        fz_default_colorspaces *default_cs,
        fz_colorspace *cs
)

function fz_set_default_cmyk

void
fz_set_default_cmyk (
        fz_context *ctx,
        fz_default_colorspaces *default_cs,
        fz_colorspace *cs
)

function fz_set_default_output_intent

void
fz_set_default_output_intent (
        fz_context *ctx,
        fz_default_colorspaces *default_cs,
        fz_colorspace *cs
)

Implementation details

Subject to change.

enum fz_rendering_intent_abuse

enum fz_rendering_intent_abuse
{
        FZ_RI_IN_SOFTMASK = 0x80
}

We abuse the top bit of the rendering intent to hold details of whether we are in a softmask or not. This should not be used by non-internal code.

struct fz_colorspace

struct fz_colorspace
{
        fz_key_storable key_storable;
        enum fz_colorspace_type type;
        int flags;
        int n;
        char *name;
        union {
#if FZ_ENABLE_ICC
                struct {
                        fz_buffer *buffer;
                        unsigned char md5[16];
                        fz_icc_profile *profile;
                } icc;
#endif
                struct {
                        fz_colorspace *base;
                        int high;
                        unsigned char *lookup;
                } indexed;
                struct {
                        fz_colorspace *base;
                        void (*eval)(fz_context *ctx, void *tint, const float *s, int sn, float *d, int dn);
                        void (*drop)(fz_context *ctx, void *tint);
                        void *tint;
                        char *colorant[FZ_MAX_COLORS];
                } separation;
        } u;
}

function fz_drop_colorspace_imp

void
fz_drop_colorspace_imp (
        fz_context *ctx,
        fz_storable *cs_
)