[Bf-blender-cvs] [9f546d69089] master: Cleanup: move public doc-strings into headers for 'imbuf'
Campbell Barton
noreply at git.blender.org
Thu Dec 9 10:04:01 CET 2021
Commit: 9f546d690899e05b25a6ef764cc8cf2f5db918b0
Author: Campbell Barton
Date: Thu Dec 9 20:01:45 2021 +1100
Branches: master
https://developer.blender.org/rB9f546d690899e05b25a6ef764cc8cf2f5db918b0
Cleanup: move public doc-strings into headers for 'imbuf'
Ref T92709
===================================================================
M source/blender/imbuf/IMB_colormanagement.h
M source/blender/imbuf/IMB_imbuf.h
M source/blender/imbuf/IMB_imbuf_types.h
M source/blender/imbuf/IMB_moviecache.h
M source/blender/imbuf/IMB_thumbs.h
M source/blender/imbuf/intern/IMB_filetype.h
M source/blender/imbuf/intern/IMB_filter.h
M source/blender/imbuf/intern/allocimbuf.c
M source/blender/imbuf/intern/bmp.c
M source/blender/imbuf/intern/cache.c
M source/blender/imbuf/intern/colormanagement.c
M source/blender/imbuf/intern/colormanagement_inline.c
M source/blender/imbuf/intern/dds/BlockDXT.cpp
M source/blender/imbuf/intern/dds/BlockDXT.h
M source/blender/imbuf/intern/dds/ColorBlock.cpp
M source/blender/imbuf/intern/dds/ColorBlock.h
M source/blender/imbuf/intern/dds/DirectDrawSurface.cpp
M source/blender/imbuf/intern/dds/DirectDrawSurface.h
M source/blender/imbuf/intern/dds/FlipDXT.cpp
M source/blender/imbuf/intern/dds/FlipDXT.h
M source/blender/imbuf/intern/divers.c
M source/blender/imbuf/intern/filter.c
M source/blender/imbuf/intern/imageprocess.c
M source/blender/imbuf/intern/iris.c
M source/blender/imbuf/intern/moviecache.c
M source/blender/imbuf/intern/openexr/openexr_api.cpp
M source/blender/imbuf/intern/openexr/openexr_api.h
M source/blender/imbuf/intern/openexr/openexr_multi.h
M source/blender/imbuf/intern/rectop.c
M source/blender/imbuf/intern/scaling.c
M source/blender/imbuf/intern/stereoimbuf.c
M source/blender/imbuf/intern/thumbs.c
M source/blender/imbuf/intern/tiff.c
M source/blender/imbuf/intern/util.c
M source/blender/imbuf/intern/util_gpu.c
===================================================================
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 ** */
+/** \} */
+
+/* ---------------------------------------------------
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list