Struct lcms2::Transform

pub struct Transform<InputPixelFormat, OutputPixelFormat, Context = GlobalContext, Flags = AllowCache> { /* private fields */ }

Conversion between two ICC profiles.

The transform ensures type safety and thread safety at compile time. To do this, it has a few generic types associated with it. Usually, you don’t need to specify any of the generic parameters (like InputPixelFormat/OutputPixelFormat) explicitly, because they are inferred from calls to constructors and transform_pixels or transform_in_place.

If you get error such as:

cannot infer type for InputPixelFormat type annotations required: cannot resolve _: std::marker::Copy

then don’t worry! Write some code that calls transform_pixels(), because this is the function that makes the type of the transform clear.

In case you need to store the transform in a struct or return from a function, the full type of Transform is:

Transform<InputPixelFormat, OutputPixelFormat, Context = GlobalContext, Flags = AllowCache>

• InputPixelFormat — e.g. (u8,u8,u8) or struct RGB<u8>, etc. The type must have appropriate number of bytes per pixel (i.e. you can’t just use [u8] for everything).
• OutputPixelFormat — similar to InputPixelFormat. If both are the same, then transform_in_place() function works.
• Context — it’s GlobalContext for the default non-thread-safe version, or ThreadContext for thread-safe version.
• Flags — AllowCache or DisallowCache. If you disallow cache, then the transform will be accessible from multiple threads.

Thread-safety:

• Transform is Send if you create it with ThreadContext (use new_*_context() functions).
• Transform is Sync if you create it without cache. Set flags to Flags::NO_CACHE.

Implementations

impl<InputPixelFormat: Copy + Pod, OutputPixelFormat: Copy + Pod> Transform<InputPixelFormat, OutputPixelFormat, GlobalContext, AllowCache>

pub fn new( input: &Profile, in_format: PixelFormat, output: &Profile, out_format: PixelFormat, intent: Intent ) -> LCMSResult<Self>

Creates a color transform for translating bitmaps.

Pixel types used in later transform_pixels calls must be either arrays or Pod #[repr(C)] structs that have appropriate number of bytes per pixel, or u8 specifically. [u8] slices are treated as a special case that is allowed for any pixel type.

Basic, non-tread-safe version.

• Input: Handle to a profile object capable to work in input direction
• InputFormat: A bit-field format specifier
• Output: Handle to a profile object capable to work in output direction
• OutputFormat: A bit-field format specifier
• Intent: Rendering intent

See documentation of these types for more detail.

pub fn new_flags<Fl: CacheFlag>( input: &Profile, in_format: PixelFormat, output: &Profile, out_format: PixelFormat, intent: Intent, flags: Flags<Fl> ) -> LCMSResult<Self>

Non-thread-safe. See Transform::new.

pub fn new_proofing( input: &Profile, in_format: PixelFormat, output: &Profile, out_format: PixelFormat, proofing: &Profile, intent: Intent, proofng_intent: Intent, flags: Flags ) -> LCMSResult<Self>

A proofing transform does emulate the colors that would appear as the image were rendered on a specific device. The obtained transform emulates the device described by the “Proofing” profile. Useful to preview final result without rendering to the physical medium.

That is, for example, with a proofing transform I can see how will look a photo of my little daughter if rendered on my HP printer. Since most printer profiles does include some sort of gamut-remapping, it is likely colors will not look as the original. Using a proofing transform, it can be done by using the appropriate function. Note that this is an important feature for final users, it is worth of all color-management stuff if the final media is not cheap.

To enable proofing and gamut check you need to include following flags:

• Flags::GAMUTCHECK: Color out of gamut are flagged to a fixed color defined by the function cmsSetAlarmCodes
• Flags::SOFTPROOFING: does emulate the Proofing device.

Pixel types used in later transform_pixels calls must be either arrays or Pod #[repr(C)] structs that have appropriate number of bytes per pixel, or u8 specifically. [u8] slices are treated as a special case that is allowed for any pixel type.

pub fn new_multiprofile( profiles: &[&Profile], in_format: PixelFormat, out_format: PixelFormat, intent: Intent, flags: Flags ) -> LCMSResult<Self>

Multiprofile transforms

User passes in an array of handles to open profiles. The returned color transform do “smelt” all profiles in a single devicelink. Color spaces must be paired with the exception of Lab/XYZ, which can be interchanged.

Pixel types used in later transform_pixels calls must be either arrays or Pod #[repr(C)] structs that have appropriate number of bytes per pixel, or u8 specifically. [u8] slices are treated as a special case that is allowed for any pixel type.

impl<PixelFormat: Copy + Pod, Ctx: Context, Fl: CacheFlag> Transform<PixelFormat, PixelFormat, Ctx, Fl>

pub fn transform_in_place(&self, srcdst: &mut [PixelFormat])

Read pixels and write them back to the same slice. Input and output pixel types must be identical.

This processes up to u32::MAX pixels.

Pixel types must be either arrays or Pod #[repr(C)] structs that have appropriate number of bytes per pixel, or u8 specifically. [u8] slices are treated as a special case that is allowed for any pixel type. When [u8] is used, it will panic if the byte length of the slice is not a round number of pixels.

impl<InputPixelFormat: Copy + Pod, OutputPixelFormat: Copy + Pod, Ctx: Context> Transform<InputPixelFormat, OutputPixelFormat, Ctx, AllowCache>

pub fn new_context( context: impl AsRef<Ctx>, input: &Profile<Ctx>, in_format: PixelFormat, output: &Profile<Ctx>, out_format: PixelFormat, intent: Intent ) -> LCMSResult<Self>

impl<InputPixelFormat: Copy + Pod, OutputPixelFormat: Copy + Pod, Ctx: Context, Fl: CacheFlag> Transform<InputPixelFormat, OutputPixelFormat, Ctx, Fl>

pub fn input_pixel_format(&self) -> PixelFormat

Description of the input pixel format this transform has been created for

pub fn output_pixel_format(&self) -> PixelFormat

Description of the output pixel format this transform has been created for

pub fn transform_pixels( &self, src: &[InputPixelFormat], dst: &mut [OutputPixelFormat] )

This function translates bitmaps according of parameters setup when creating the color transform.

If slices differ in length, the smaller amount of pixels is processed. This processes up to u32::MAX pixels.

Pixel types must be either arrays or Pod #[repr(C)] structs that have appropriate number of bytes per pixel, or u8 specifically. [u8] slices are treated as a special case that is allowed for any pixel type. When [u8] is used, it will panic if the byte length of the slice is not a round number of pixels.

pub fn transform_pixels_uninit<'dst>( &self, src: &[InputPixelFormat], dst: &'dst mut [MaybeUninit<OutputPixelFormat>] ) -> &'dst mut [OutputPixelFormat]

This function translates bitmaps according of parameters setup when creating the color transform.

It allows destination to be uninitailized, and returns the same slice, initialized.

Panics

If the source slice is shorter than the destination, or larger than u32::MAX. When [u8] is used, it will panic if the byte length of the slice is not a round number of pixels.

pub fn new_flags_context( context: impl AsRef<Ctx>, input: &Profile<Ctx>, in_format: PixelFormat, output: &Profile<Ctx>, out_format: PixelFormat, intent: Intent, flags: Flags<Fl> ) -> LCMSResult<Self>

pub fn new_proofing_context( context: impl AsRef<Ctx>, input: &Profile<Ctx>, in_format: PixelFormat, output: &Profile<Ctx>, out_format: PixelFormat, proofing: &Profile<Ctx>, intent: Intent, proofng_intent: Intent, flags: Flags<Fl> ) -> LCMSResult<Self>

pub fn new_multiprofile_context( context: impl AsRef<Ctx>, profiles: &[&Profile<Ctx>], in_format: PixelFormat, out_format: PixelFormat, intent: Intent, flags: Flags<Fl> ) -> LCMSResult<Self>

impl<F, T, C, L> Transform<F, T, C, L>

pub fn input_format(&self) -> PixelFormat

pub fn output_format(&self) -> PixelFormat

impl<F, T, L> Transform<F, T, GlobalContext, L>

pub fn global_adaptation_state() -> f64

Adaptation state for absolute colorimetric intent, on all but cmsCreateExtendedTransform.

See ThreadContext::adaptation_state()

pub fn set_global_adaptation_state(value: f64)

👎Deprecated: Use ThreadContext::set_adaptation_state()

Sets adaptation state for absolute colorimetric intent, on all but cmsCreateExtendedTransform. Little CMS can handle incomplete adaptation states.

See ThreadContext::set_adaptation_state()

Degree on adaptation 0=Not adapted, 1=Complete adaptation, in-between=Partial adaptation.

pub fn set_global_alarm_codes(codes: [u16; 16])

👎Deprecated: Use ThreadContext::set_alarm_codes()

Sets the global codes used to mark out-out-gamut on Proofing transforms. Values are meant to be encoded in 16 bits. AlarmCodes: Array [16] of codes. ALL 16 VALUES MUST BE SPECIFIED, set to zero unused channels.

See ThreadContext::set_alarm_codes()

pub fn global_alarm_codes() -> [u16; 16]

Gets the current global codes used to mark out-out-gamut on Proofing transforms. Values are meant to be encoded in 16 bits.

See ThreadContext::alarm_codes()

Trait Implementations

impl<F, T, C, L> Debug for Transform<F, T, C, L>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F, T, C, L> Drop for Transform<F, T, C, L>

fn drop(&mut self)

Executes the destructor for this type.

impl<F, T, C: Send, Z> Send for Transform<F, T, C, Z>