diff options
Diffstat (limited to 'source/blender/imbuf/IMB_colormanagement.h')
| -rw-r--r-- | source/blender/imbuf/IMB_colormanagement.h | 198 |
1 files changed, 179 insertions, 19 deletions
diff --git a/source/blender/imbuf/IMB_colormanagement.h b/source/blender/imbuf/IMB_colormanagement.h index 53b0e295385..3ea8ac47f17 100644 --- a/source/blender/imbuf/IMB_colormanagement.h +++ b/source/blender/imbuf/IMB_colormanagement.h @@ -45,7 +45,9 @@ struct bContext; struct ColorManagedDisplay; struct ColorSpace; -/* ** Generic functions ** */ +/* -------------------------------------------------------------------- */ +/** \name Generic Functions + * \{ */ void IMB_colormanagement_check_file_config(struct Main *bmain); @@ -67,13 +69,35 @@ bool IMB_colormanagement_space_is_scene_linear(struct ColorSpace *colorspace); bool IMB_colormanagement_space_is_srgb(struct ColorSpace *colorspace); bool IMB_colormanagement_space_name_is_data(const char *name); +/** + * Convert a float RGB triplet to the correct luminance weighted average. + * + * Grayscale, or Luma is a distillation of RGB data values down to a weighted average + * based on the luminance positions of the red, green, and blue primaries. + * Given that the internal reference space may be arbitrarily set, any + * effort to glean the luminance coefficients must be aware of the reference + * space primaries. + * + * See http://wiki.blender.org/index.php/User:Nazg-gul/ColorManagement#Luminance + */ BLI_INLINE float IMB_colormanagement_get_luminance(const float rgb[3]); +/** + * Byte equivalent of #IMB_colormanagement_get_luminance(). + */ BLI_INLINE unsigned char IMB_colormanagement_get_luminance_byte(const unsigned char[3]); BLI_INLINE void IMB_colormanagement_xyz_to_rgb(float rgb[3], const float xyz[3]); BLI_INLINE void IMB_colormanagement_rgb_to_xyz(float xyz[3], const float rgb[3]); const float *IMB_colormanagement_get_xyz_to_rgb(void); -/* ** Color space transformation functions ** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Color Space Transformation Functions + * \{ */ + +/** + * Convert the whole buffer from specified by name color space to another. + */ void IMB_colormanagement_transform(float *buffer, int width, int height, @@ -81,6 +105,10 @@ void IMB_colormanagement_transform(float *buffer, const char *from_colorspace, const char *to_colorspace, bool predivide); +/** + * Convert the whole buffer from specified by name color space to another + * will do threaded conversion. + */ void IMB_colormanagement_transform_threaded(float *buffer, int width, int height, @@ -88,6 +116,9 @@ void IMB_colormanagement_transform_threaded(float *buffer, const char *from_colorspace, const char *to_colorspace, bool predivide); +/** + * Similar to #IMB_colormanagement_transform_threaded, but operates on byte buffer. + */ void IMB_colormanagement_transform_byte(unsigned char *buffer, int width, int height, @@ -100,6 +131,9 @@ void IMB_colormanagement_transform_byte_threaded(unsigned char *buffer, int channels, const char *from_colorspace, const char *to_colorspace); +/** + * Similar to #IMB_colormanagement_transform_byte_threaded, but gets float buffer from display one. + */ void IMB_colormanagement_transform_from_byte(float *float_buffer, unsigned char *byte_buffer, int width, @@ -118,12 +152,20 @@ void IMB_colormanagement_transform_v4(float pixel[4], const char *from_colorspace, const char *to_colorspace); +/** + * Convert pixel from specified by descriptor color space to scene linear + * used by performance-critical areas such as renderer and baker. + */ void IMB_colormanagement_colorspace_to_scene_linear_v3(float pixel[3], struct ColorSpace *colorspace); void IMB_colormanagement_colorspace_to_scene_linear_v4(float pixel[4], bool predivide, struct ColorSpace *colorspace); +/** + * Same as #IMB_colormanagement_colorspace_to_scene_linear_v4, + * but converts colors in opposite direction. + */ void IMB_colormanagement_scene_linear_to_colorspace_v3(float pixel[3], struct ColorSpace *colorspace); @@ -150,14 +192,36 @@ void IMB_colormanagement_imbuf_to_float_texture(float *out_buffer, const struct ImBuf *ibuf, const bool store_premultiplied); +/** + * Conversion between color picking role. Typically we would expect such a + * requirements: + * - It is approximately perceptually linear, so that the HSV numbers and + * the HSV cube/circle have an intuitive distribution. + * - It has the same gamut as the scene linear color space. + * - Color picking values 0..1 map to scene linear values in the 0..1 range, + * so that picked albedo values are energy conserving. + */ void IMB_colormanagement_scene_linear_to_color_picking_v3(float pixel[3]); void IMB_colormanagement_color_picking_to_scene_linear_v3(float pixel[3]); +/** + * Conversion between sRGB, for rare cases like hex color or copy/pasting + * between UI theme and scene linear colors. + */ void IMB_colormanagement_scene_linear_to_srgb_v3(float pixel[3]); void IMB_colormanagement_srgb_to_scene_linear_v3(float pixel[3]); +/** + * Convert pixel from scene linear to display space using default view + * used by performance-critical areas such as color-related widgets where we want to reduce + * amount of per-widget allocations. + */ void IMB_colormanagement_scene_linear_to_display_v3(float pixel[3], struct ColorManagedDisplay *display); +/** + * Same as #IMB_colormanagement_scene_linear_to_display_v3, + * but converts color in opposite direction. + */ void IMB_colormanagement_display_to_scene_linear_v3(float pixel[3], struct ColorManagedDisplay *display); @@ -178,6 +242,18 @@ void IMB_colormanagement_imbuf_make_display_space( const struct ColorManagedViewSettings *view_settings, const struct ColorManagedDisplaySettings *display_settings); +/** + * Prepare image buffer to be saved on disk, applying color management if needed + * color management would be applied if image is saving as render result and if + * file format is not expecting float buffer to be in linear space (currently + * JPEG2000 and TIFF are such formats -- they're storing image as float but + * file itself stores applied color space). + * + * Both byte and float buffers would contain applied color space, and result's + * float_colorspace would be set to display color space. This should be checked + * in image format write callback and if float_colorspace is not NULL, no color + * space transformation should be applied on this buffer. + */ struct ImBuf *IMB_colormanagement_imbuf_for_write( struct ImBuf *ibuf, bool save_as_render, @@ -196,7 +272,11 @@ void IMB_colormanagement_buffer_make_display_space( const struct ColorManagedViewSettings *view_settings, const struct ColorManagedDisplaySettings *display_settings); -/* ** Public display buffers interfaces ** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Public Display Buffers Interfaces + * \{ */ void IMB_colormanagement_display_settings_from_ctx( const struct bContext *C, @@ -207,11 +287,17 @@ const char *IMB_colormanagement_get_display_colorspace_name( const struct ColorManagedViewSettings *view_settings, const struct ColorManagedDisplaySettings *display_settings); +/** + * Acquire display buffer for given image buffer using specified view and display settings. + */ unsigned char *IMB_display_buffer_acquire( struct ImBuf *ibuf, const struct ColorManagedViewSettings *view_settings, const struct ColorManagedDisplaySettings *display_settings, void **cache_handle); +/** + * Same as #IMB_display_buffer_acquire but gets view and display settings from context. + */ unsigned char *IMB_display_buffer_acquire_ctx(const struct bContext *C, struct ImBuf *ibuf, void **cache_handle); @@ -227,24 +313,47 @@ void IMB_display_buffer_transform_apply(unsigned char *display_buffer, void IMB_display_buffer_release(void *cache_handle); -/* ** Display functions ** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Display Functions + * \{ */ + int IMB_colormanagement_display_get_named_index(const char *name); const char *IMB_colormanagement_display_get_indexed_name(int index); const char *IMB_colormanagement_display_get_default_name(void); +/** + * Used by performance-critical pixel processing areas, such as color widgets. + */ struct ColorManagedDisplay *IMB_colormanagement_display_get_named(const char *name); const char *IMB_colormanagement_display_get_none_name(void); const char *IMB_colormanagement_display_get_default_view_transform_name( struct ColorManagedDisplay *display); -/* ** View functions ** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name View Functions + * \{ */ + int IMB_colormanagement_view_get_named_index(const char *name); const char *IMB_colormanagement_view_get_indexed_name(int index); -/* ** Look functions ** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Look Functions + * \{ */ + int IMB_colormanagement_look_get_named_index(const char *name); const char *IMB_colormanagement_look_get_indexed_name(int index); -/* ** Color space functions ** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Color Space Functions + * \{ */ + int IMB_colormanagement_colorspace_get_named_index(const char *name); const char *IMB_colormanagement_colorspace_get_indexed_name(int index); const char *IMB_colormanagement_view_get_default_name(const char *display_name); @@ -252,7 +361,12 @@ const char *IMB_colormanagement_view_get_default_name(const char *display_name); void IMB_colormanagement_colorspace_from_ibuf_ftype( struct ColorManagedColorspaceSettings *colorspace_settings, struct ImBuf *ibuf); -/* ** RNA helper functions ** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name RNA Helper Functions + * \{ */ + void IMB_colormanagement_display_items_add(struct EnumPropertyItem **items, int *totitem); void IMB_colormanagement_view_items_add(struct EnumPropertyItem **items, int *totitem, @@ -262,7 +376,12 @@ void IMB_colormanagement_look_items_add(struct EnumPropertyItem **items, const char *view_name); void IMB_colormanagement_colorspace_items_add(struct EnumPropertyItem **items, int *totitem); -/* ** Tile-based buffer management ** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Tile-based Buffer Management + * \{ */ + void IMB_partial_display_buffer_update(struct ImBuf *ibuf, const float *linear_buffer, const unsigned char *byte_buffer, @@ -293,7 +412,12 @@ void IMB_partial_display_buffer_update_threaded( void IMB_partial_display_buffer_update_delayed( struct ImBuf *ibuf, int xmin, int ymin, int xmax, int ymax); -/* ** Pixel processor functions ** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Pixel Processor Functions + * \{ */ + struct ColormanageProcessor *IMB_colormanagement_display_processor_new( const struct ColorManagedViewSettings *view_settings, const struct ColorManagedDisplaySettings *display_settings); @@ -321,17 +445,40 @@ void IMB_colormanagement_processor_apply_byte(struct ColormanageProcessor *cm_pr int channels); void IMB_colormanagement_processor_free(struct ColormanageProcessor *cm_processor); -/* ** OpenGL drawing routines using GLSL for color space transform ** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name OpenGL Drawing Routines Using GLSL for Color Space Transform + * \{ */ -/* Test if GLSL drawing is supported for combination of graphics card and this configuration */ +/** + * Test if GLSL drawing is supported for combination of graphics card and this configuration. + */ bool IMB_colormanagement_support_glsl_draw(const struct ColorManagedViewSettings *view_settings); -/* Configures GLSL shader for conversion from scene linear to display space */ +/** + * Configures GLSL shader for conversion from scene linear to display space. + */ bool IMB_colormanagement_setup_glsl_draw( const struct ColorManagedViewSettings *view_settings, const struct ColorManagedDisplaySettings *display_settings, float dither, bool predivide); -/* Same as above, but display space conversion happens from a specified space */ +/** + * \note Same as IMB_colormanagement_setup_glsl_draw, + * but display space conversion happens from a specified space. + * + * Configures GLSL shader for conversion from specified to + * display color space + * + * Will create appropriate OCIO processor and setup GLSL shader, + * so further 2D texture usage will use this conversion. + * + * When there's no need to apply transform on 2D textures, use + * IMB_colormanagement_finish_glsl_draw(). + * + * This is low-level function, use ED_draw_imbuf_ctx if you + * only need to display given image buffer + */ bool IMB_colormanagement_setup_glsl_draw_from_space( const struct ColorManagedViewSettings *view_settings, const struct ColorManagedDisplaySettings *display_settings, @@ -339,20 +486,31 @@ bool IMB_colormanagement_setup_glsl_draw_from_space( float dither, bool predivide, bool do_overlay_merge); -/* Same as setup_glsl_draw, but color management settings are guessing from a given context */ +/** + * Same as setup_glsl_draw, but color management settings are guessing from a given context. + */ bool IMB_colormanagement_setup_glsl_draw_ctx(const struct bContext *C, float dither, bool predivide); -/* Same as setup_glsl_draw_from_space, - * but color management settings are guessing from a given context. */ +/** + * Same as `setup_glsl_draw_from_space`, + * but color management settings are guessing from a given context. + */ bool IMB_colormanagement_setup_glsl_draw_from_space_ctx(const struct bContext *C, struct ColorSpace *colorspace, float dither, bool predivide); -/* Finish GLSL-based display space conversion */ +/** + * Finish GLSL-based display space conversion. + */ void IMB_colormanagement_finish_glsl_draw(void); -/* ** View transform ** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name View Transform + * \{ */ + void IMB_colormanagement_init_default_view_settings( struct ColorManagedViewSettings *view_settings, const struct ColorManagedDisplaySettings *display_settings); @@ -368,6 +526,8 @@ enum { COLOR_ROLE_DATA, }; +/** \} */ + #ifdef __cplusplus } #endif |