pdfium_render/pdf/
color_space.rs

1//! Defines the [PdfColorSpace] enum, defining all the color spaces supported by the PDF file format.
2
3use crate::bindgen::{
4    FPDF_COLORSPACE_CALGRAY, FPDF_COLORSPACE_CALRGB, FPDF_COLORSPACE_DEVICECMYK, FPDF_COLORSPACE_DEVICEGRAY,
5    FPDF_COLORSPACE_DEVICEN, FPDF_COLORSPACE_DEVICERGB, FPDF_COLORSPACE_ICCBASED, FPDF_COLORSPACE_INDEXED,
6    FPDF_COLORSPACE_LAB, FPDF_COLORSPACE_PATTERN, FPDF_COLORSPACE_SEPARATION, FPDF_COLORSPACE_UNKNOWN,
7};
8use crate::error::PdfiumError;
9
10#[cfg(doc)]
11use crate::pdf::document::page::PdfPage;
12
13/// The color space of any displayable object on a [PdfPage].
14///
15/// Colors can be described in any of a variety of color systems called _color spaces_.
16/// Some color spaces are related to device color representation (e.g. grayscale, RGB, CMYK);
17/// others are related to human visual perception.
18///
19/// Color spaces can be classified into _color space families_. Spaces within a family
20/// share the same general characteristics. Families fall into three broad categories:
21///
22/// * **Device color spaces** directly specify colors or shades of gray that the output
23///   device is to produce. The precise displayed color is device-specific and is not calibrated.
24///   Color space families in this category include [PdfColorSpace::DeviceGray],
25///   [PdfColorSpace::DeviceRGB], and [PdfColorSpace::DeviceCMYK].
26/// * **Calibrated color spaces** are based on international standards for specifying human-visible
27///   colors created by the Commission Internationale de l'Éclairage (International Commission on
28///   Illumination) and the International Color Consortium. The precise displayed color is
29///   device-independent; it does not rely on the characteristics of any particular output device.
30///   Color space families in this category include [PdfColorSpace::CalibratedCIEGray],
31///   [PdfColorSpace::CalibratedCIERGB], [PdfColorSpace::CalibratedCIELab], and
32///   [PdfColorSpace::CalibratedICCProfile].
33/// * **Special color spaces** add features or properties to another color space, such as
34///   patterns, color mapping, separations, and high-fidelity and/or multi-tone color.
35///   Color space families in this category include [PdfColorSpace::Pattern],
36///   [PdfColorSpace::Indexed], [PdfColorSpace::Separation], and [PdfColorSpace::DeviceN].
37///
38/// Non-RGB color spaces typically define a transform that enables color values in the color
39/// space to be converted to an RGB approximation for on-screen display.
40///
41/// For more information on color spaces and their utilization in PDF files, see Section 4.5
42/// of the PDF Reference Manual version 1.7, starting on page 235.
43#[derive(Copy, Clone, Debug, PartialEq)]
44pub enum PdfColorSpace {
45    /// An unknown or unset color space. Color spaces were added to the PDF file format
46    /// gradually from versions 1.1 to versions 1.3.
47    Unknown = FPDF_COLORSPACE_UNKNOWN as isize,
48
49    /// Black, white, and intermediate shades of gray are special cases of full color.
50    /// A grayscale value is represented by a single number in the range `0.0..=1.0`, where
51    /// 0.0 corresponds to black, 1.0 to white, and intermediate values to different gray levels.
52    ///
53    /// This is a non-calibrated color space; the exact color produced for a particular set of
54    /// component values may vary slightly from device to device.
55    DeviceGray = FPDF_COLORSPACE_DEVICEGRAY as isize,
56
57    /// Colors in this color space are specified according to the additive Red-Green-Blue color
58    /// model used by light-emitting displays and projectors. Color values are defined by three
59    /// components representing the intensities of the additive primary colorants red, green,
60    /// and blue. Each component is specified by a number in the range `0.0..=1.0`, where
61    /// 0.0 corresponds to a complete absence of the component and 1.0 corresponds to maximum
62    /// intensity of the component. If all three components have equal intensity, the perceived
63    /// result theoretically is a pure gray on the scale from black to white. If the intensities
64    /// are not all equal, the result is some color other than a pure gray.
65    ///
66    /// This is a non-calibrated color space; the exact color produced for a particular set of
67    /// component values may vary slightly from device to device.
68    DeviceRGB = FPDF_COLORSPACE_DEVICERGB as isize,
69
70    /// Colors in this color space are specified according to the subtractive Cyan-Magenta-Yellow-Black
71    /// model typical of printers and other paper-based output devices. In theory, each of the three
72    /// standard process colorants used in printing (cyan, magenta, and yellow) absorbs one of the
73    /// additive primary colors (red, green, and blue, respectively). Black, a fourth standard process
74    /// colorant, absorbs all of the additive primaries in equal amounts. Color values are defined
75    /// by four components representing the concentrations of these process colorants. Each component
76    /// is specified by a number in the range `0.0..=1.0`, where 0.0 denotes the complete absence of
77    /// a process colorant (that is, absorbs none of the corresponding additive primary) and 1.0
78    /// denotes maximum concentration (absorbs as much as possible of the additive primary). Note
79    /// that the sense of these numbers is opposite to that of RGB color components.
80    ///
81    /// This is a non-calibrated color space; the exact color produced for a particular set of
82    /// component values may vary slightly from device to device.
83    DeviceCMYK = FPDF_COLORSPACE_DEVICECMYK as isize,
84
85    /// Colors in this color space are specified by a single component, arbitrarily named A,
86    /// that represents the gray component of a calibrated gray color space.
87    ///
88    /// This is a calibrated color space, based on the tristimulus components of the CIE 1931 XYZ
89    /// color space. The three components of the color space are defined in terms of human
90    /// color vision and are independent of any particular output device.
91    CalibratedCIEGray = FPDF_COLORSPACE_CALGRAY as isize,
92
93    /// Colors in this color space are specified by three components, arbitrarily named A, B, and C,
94    /// representing calibrated red, green, and blue color values. These three color components must
95    /// be in the range `0.0..=1.0`.
96    ///
97    /// This is a calibrated color space, based on the tristimulus components of the CIE 1931 XYZ
98    /// color space. The three components of the color space are defined in terms of human
99    /// color vision and are independent of any particular output device.
100    CalibratedCIERGB = FPDF_COLORSPACE_CALRGB as isize,
101
102    /// Colors in this color space are specified by three components, named L*, a*, and b*,
103    /// of a CIE 1976 L\*a\*b color space. The range of the first (L*) component is always 0 to 100;
104    /// the ranges of the second (a*) and third (b*) components are defined by the color space.
105    ///
106    /// This is a calibrated color space; the three components of the color space are defined in
107    /// terms of human color vision and are independent of any particular output device.
108    CalibratedCIELab = FPDF_COLORSPACE_LAB as isize,
109
110    /// Colors in this color space are based on a cross-platform color profile defined by
111    /// the International Color Consortium (ICC).
112    ///
113    /// This is a calibrated color space; colors are defined by international standards
114    /// and are independent of any particular output device.
115    CalibratedICCProfile = FPDF_COLORSPACE_ICCBASED as isize,
116
117    /// Some output devices, such as image-setters, produce a separate, monochromatic rendition of
118    /// a page - a _separation_ - for each colorant. When the separations are later combined - on a
119    /// printing press, for example - with proper inks or other colorants added to them, the result
120    /// is a full-color page.
121    ///
122    /// This special color space provides a means for specifying the use of additional colorants,
123    /// called a _tint_, or for isolating the control of individual color components of a device
124    /// color space for a subtractive device.
125    Separation = FPDF_COLORSPACE_SEPARATION as isize,
126
127    /// Colors in this special color space can contain an arbitrary number of color components.
128    /// This provides greater flexibility than is possible with standard device color spaces
129    /// or with individual separation color spaces. DeviceN color spaces are used in applications
130    /// such as high-fidelity color (such as the Pantone Hexachrome system), multi-tone
131    /// color systems (such as duotone), and spot color systems (using subtractive colorants outside
132    /// the standard Cyan-Magenta-Yellow-Black model).
133    DeviceN = FPDF_COLORSPACE_DEVICEN as isize,
134
135    /// This special color space indicates an object or area should be painted according to
136    /// color values stored in a lookup table rather than a color space.
137    Indexed = FPDF_COLORSPACE_INDEXED as isize,
138
139    /// This special color space indicates an object or area should be painted using a pattern,
140    /// rather than a single color.
141    Pattern = FPDF_COLORSPACE_PATTERN as isize,
142}
143
144impl PdfColorSpace {
145    pub(crate) fn from_pdfium(value: u32) -> Result<PdfColorSpace, PdfiumError> {
146        match value {
147            FPDF_COLORSPACE_CALGRAY => Ok(PdfColorSpace::CalibratedCIEGray),
148            FPDF_COLORSPACE_CALRGB => Ok(PdfColorSpace::CalibratedCIERGB),
149            FPDF_COLORSPACE_DEVICECMYK => Ok(PdfColorSpace::DeviceCMYK),
150            FPDF_COLORSPACE_DEVICEGRAY => Ok(PdfColorSpace::DeviceGray),
151            FPDF_COLORSPACE_DEVICEN => Ok(PdfColorSpace::DeviceN),
152            FPDF_COLORSPACE_DEVICERGB => Ok(PdfColorSpace::DeviceRGB),
153            FPDF_COLORSPACE_ICCBASED => Ok(PdfColorSpace::CalibratedICCProfile),
154            FPDF_COLORSPACE_INDEXED => Ok(PdfColorSpace::Indexed),
155            FPDF_COLORSPACE_LAB => Ok(PdfColorSpace::CalibratedCIELab),
156            FPDF_COLORSPACE_PATTERN => Ok(PdfColorSpace::Pattern),
157            FPDF_COLORSPACE_SEPARATION => Ok(PdfColorSpace::Separation),
158            FPDF_COLORSPACE_UNKNOWN => Ok(PdfColorSpace::Unknown),
159            _ => Err(PdfiumError::UnknownPdfColorSpace),
160        }
161    }
162}
pdfium_render/pdf/color_space.rs

pdfium_render/pdf/
color_space.rs
