[gtk+] docs: Point at for_scale() variants

[Emmanuele Bassi <ebassi src gnome org>]

commit c1ecd1ef9da16c2bbc3b1e735f56dad0c74521ef
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Wed Nov 4 11:50:37 2015 +0000

    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.

 gtk/gtkicontheme.c |   12 ++++++++++++
 1 files changed, 12 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index eb89bf4..38d5d36 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()