docs: Point at for_scale() variants

Using lookup_icon() and lookup_by_gicon() with a size multiplied by a
scaling factor is almost certainly going to get worse results than using
their for_scale() variants.

1 files changed, 12 insertions, 0 deletions

diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index eb89bf4cd6..38d5d36602 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -1995,6 +1995,12 @@ choose_icon (GtkIconTheme       *icon_theme,
  * can then be rendered into a pixbuf using
  * gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon()
  * combines these two steps if all you need is the pixbuf.)
+ *
+ * When rendering on displays with high pixel densities you should not
+ * use a @size multiplied by the scaling factor returned by functions
+ * like gdk_window_get_scale_factor(). Instead, you should use
+ * gtk_icon_theme_lookup_icon_for_scale(), as the assets loaded
+ * for a given scaling factor may be different.
  * 
  * Returns: (nullable) (transfer full): a #GtkIconInfo object
  *     containing information about the icon, or %NULL if the
@@ -5379,6 +5385,12 @@ find_builtin_icon (const gchar *icon_name,
  * such as the filename of the icon. The icon can then be rendered
  * into a pixbuf using gtk_icon_info_load_icon().
  *
+ * When rendering on displays with high pixel densities you should not
+ * use a @size multiplied by the scaling factor returned by functions
+ * like gdk_window_get_scale_factor(). Instead, you should use
+ * gtk_icon_theme_lookup_by_gicon_for_scale(), as the assets loaded
+ * for a given scaling factor may be different.
+ *
  * Returns: (nullable) (transfer full): a #GtkIconInfo containing
  *     information about the icon, or %NULL if the icon wasn’t
  *     found. Unref with g_object_unref()