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

pdfium_render/pdf/
color_space.rs
