Add glfwSetApplicationIcon

Closes #2041

New API: glfwSetApplication.
Stubs emitting GLFW_FEATURE_UNIMPLEMENTED for X11, Wayland and Win32.
Cocoa implementation selects the largest image provided.
Updated the icon test to also update the application icon.

CONTRIBUTORS.md

@@ -99,6 +99,7 @@ video tutorials.
  - Aaron Jacobs
  - JannikGM
  - Erik S. V. Jansson
+ - Andreas O. Jansen
  - jjYBdx4IL
  - Toni Jovanoski
  - Arseny Kapoulkine

README.md

@@ -121,6 +121,7 @@ information on what to include when reporting a bug.
 
 ## Changelog
 
+ - Added `glfwSetApplicationIcon` to set the application's icon (#2041)
  - Added `GLFW_PLATFORM` init hint for runtime platform selection (#1958)
  - Added `GLFW_ANY_PLATFORM`, `GLFW_PLATFORM_WIN32`, `GLFW_PLATFORM_COCOA`,
    `GLFW_PLATFORM_WAYLAND`, `GLFW_PLATFORM_X11` and `GLFW_PLATFORM_NULL` symbols to

include/GLFW/glfw3.h

@@ -2475,6 +2475,51 @@ GLFWAPI int glfwGetPlatform(void);
  */
 GLFWAPI int glfwPlatformSupported(int platform);
 
+/*! @brief Sets the icon for the application.
+ *
+ *  This function sets the run-time icon of the application.  If passed an array of
+ *  candidate images, those of or closest to the sizes desired by the system are
+ *  selected.  If no images are specified, the window reverts to its default
+ *  icon.
+ *
+ *  The pixels are 32-bit, little-endian, non-premultiplied RGBA, i.e. eight
+ *  bits per channel with the red channel first.  They are arranged canonically
+ *  as packed sequential rows, starting from the top-left corner.
+ *
+ *  The desired image sizes varies depending on platform and system settings.
+ *  The selected images will be rescaled as needed.  Good sizes include 16x16,
+ *  32x32 and 48x48.
+ *
+ *  @param[in] count The number of images in the specified array, or zero to
+ *  revert to the default window icon.
+ *  @param[in] images The images to create the icon from.  This is ignored if
+ *  count is zero.
+ *
+ *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
+ *  GLFW_INVALID_VALUE, @ref GLFW_PLATFORM_ERROR and @ref
+ *  GLFW_FEATURE_UNAVAILABLE (see remarks).
+ *
+ *  @pointer_lifetime The specified image data is copied before this function
+ *  returns.
+ *
+ *  @remark @macos Sets the Dock icon. Currently selects the largest image.
+ *
+ *  @remark @win32 This function will emit @ref GLFW_FEATURE_UNIMPLEMENTED.
+ *
+ *  @remark @x11 This function will emit @ref GLFW_FEATURE_UNIMPLEMENTED.
+ *
+ *  @remark @wayland This function will emit @ref GLFW_FEATURE_UNIMPLEMENTED.
+ *
+ *  @thread_safety This function must only be called from the main thread.
+ *
+ *  @sa @ref window_icon
+ *
+ *  @since Added in version 3.4.
+ *
+ *  @ingroup init
+ */
+GLFWAPI void glfwSetApplicationIcon(int count, const GLFWimage* images);
+
 /*! @brief Returns the currently connected monitors.
  *
  *  This function returns an array of handles for all currently connected

src/cocoa_init.m

@@ -498,6 +498,7 @@ GLFWbool _glfwConnectCocoa(int platformID, _GLFWplatform* platform)
         GLFW_PLATFORM_COCOA,
         _glfwInitCocoa,
         _glfwTerminateCocoa,
+        _glfwSetApplicationIconCocoa,
         _glfwGetCursorPosCocoa,
         _glfwSetCursorPosCocoa,
         _glfwSetCursorModeCocoa,
@@ -693,5 +694,62 @@ void _glfwTerminateCocoa(void)
     } // autoreleasepool
 }
 
+void _glfwSetApplicationIconCocoa(int count, const GLFWimage* images)
+{
+    @autoreleasepool {
+    if (count == 0)
+    {
+        NSApp.applicationIconImage = nil;
+        return;
+    }
+    
+    // Selects the largest image. Should probably select the one with the
+    // size most similar to the current NSApp.applicationIconImage.size.
+    int imageIndex = 0;
+    for (int i = 1; i < count; ++i)
+    {
+        if (images[i].width > images[imageIndex].width ||
+            images[i].height > images[imageIndex].height)
+            imageIndex = i;
+    }
+    
+    const GLFWimage* image = images + imageIndex;
+    
+    assert(image->pixels != NULL);
+    
+    NSImage* native;
+    NSBitmapImageRep* rep;
+
+    rep = [[NSBitmapImageRep alloc]
+        initWithBitmapDataPlanes:NULL
+                      pixelsWide:image->width
+                      pixelsHigh:image->height
+                   bitsPerSample:8
+                 samplesPerPixel:4
+                        hasAlpha:YES
+                        isPlanar:NO
+                  colorSpaceName:NSCalibratedRGBColorSpace
+                    bitmapFormat:NSBitmapFormatAlphaNonpremultiplied
+                     bytesPerRow:image->width * 4
+                    bitsPerPixel:32];
+
+    if (rep == nil)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR, NULL);
+        return;
+    }
+    
+    memcpy([rep bitmapData], image->pixels, image->width * image->height * 4);
+
+    native = [[NSImage alloc] initWithSize:NSMakeSize(image->width, image->height)];
+    [native addRepresentation:rep];
+
+    NSApp.applicationIconImage = native;
+    
+    [native release];
+    [rep release];
+    }
+}
+
 #endif // _GLFW_COCOA
 

src/cocoa_platform.h

@@ -213,6 +213,7 @@ typedef struct _GLFWcursorNS
 GLFWbool _glfwConnectCocoa(int platformID, _GLFWplatform* platform);
 int _glfwInitCocoa(void);
 void _glfwTerminateCocoa(void);
+void _glfwSetApplicationIconCocoa(int count, const GLFWimage* images);
 
 GLFWbool _glfwCreateWindowCocoa(_GLFWwindow* window, const _GLFWwndconfig* wndconfig, const _GLFWctxconfig* ctxconfig, const _GLFWfbconfig* fbconfig);
 void _glfwDestroyWindowCocoa(_GLFWwindow* window);

src/init.c

@@ -543,3 +543,8 @@ GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun)
     return cbfun;
 }
 
+GLFWAPI void glfwSetApplicationIcon(int count, const GLFWimage* images)
+{
+    assert(count == 0 || images != NULL);
+    _glfw.platform.setApplicationIcon(count, images);
+}

src/internal.h

@@ -673,6 +673,7 @@ struct _GLFWplatform
     // init
     GLFWbool (*init)(void);
     void (*terminate)(void);
+    void (*setApplicationIcon)(int,const GLFWimage*);
     // input
     void (*getCursorPos)(_GLFWwindow*,double*,double*);
     void (*setCursorPos)(_GLFWwindow*,double,double);

src/null_init.c

@@ -43,6 +43,7 @@ GLFWbool _glfwConnectNull(int platformID, _GLFWplatform* platform)
         GLFW_PLATFORM_NULL,
         _glfwInitNull,
         _glfwTerminateNull,
+        _glfwSetApplicationIconNull,
         _glfwGetCursorPosNull,
         _glfwSetCursorPosNull,
         _glfwSetCursorModeNull,
@@ -131,3 +132,7 @@ void _glfwTerminateNull(void)
     _glfwTerminateEGL();
 }
 
+void _glfwSetApplicationIconNull(int count, const GLFWimage* images)
+{
+    // Silently ignore
+}

src/null_platform.h

@@ -75,6 +75,7 @@ void _glfwPollMonitorsNull(void);
 GLFWbool _glfwConnectNull(int platformID, _GLFWplatform* platform);
 int _glfwInitNull(void);
 void _glfwTerminateNull(void);
+void _glfwSetApplicationIconNull(int count, const GLFWimage* images);
 
 void _glfwFreeMonitorNull(_GLFWmonitor* monitor);
 void _glfwGetMonitorPosNull(_GLFWmonitor* monitor, int* xpos, int* ypos);

src/win32_init.c

@@ -608,6 +608,7 @@ GLFWbool _glfwConnectWin32(int platformID, _GLFWplatform* platform)
         GLFW_PLATFORM_WIN32,
         _glfwInitWin32,
         _glfwTerminateWin32,
+        _glfwSetApplicationIconWin32,
         _glfwGetCursorPosWin32,
         _glfwSetCursorPosWin32,
         _glfwSetCursorModeWin32,
@@ -727,5 +728,12 @@ void _glfwTerminateWin32(void)
     freeLibraries();
 }
 
+void _glfwSetApplicationIconWin32(int count, const GLFWimage* images)
+{
+    // TODO
+    _glfwInputError(GLFW_FEATURE_UNIMPLEMENTED,
+                    "Win32: Application icon setting not implemented yet");
+}
+
 #endif // _GLFW_WIN32
 

src/win32_platform.h

@@ -526,6 +526,7 @@ typedef struct _GLFWcursorWin32
 GLFWbool _glfwConnectWin32(int platformID, _GLFWplatform* platform);
 int _glfwInitWin32(void);
 void _glfwTerminateWin32(void);
+void _glfwSetApplicationIconWin32(int count, const GLFWimage* images);
 
 WCHAR* _glfwCreateWideStringFromUTF8Win32(const char* source);
 char* _glfwCreateUTF8FromWideStringWin32(const WCHAR* source);

src/wl_init.c

@@ -381,6 +381,7 @@ GLFWbool _glfwConnectWayland(int platformID, _GLFWplatform* platform)
         GLFW_PLATFORM_WAYLAND,
         _glfwInitWayland,
         _glfwTerminateWayland,
+        _glfwSetApplicationIconWayland,
         _glfwGetCursorPosWayland,
         _glfwSetCursorPosWayland,
         _glfwSetCursorModeWayland,
@@ -793,5 +794,12 @@ void _glfwTerminateWayland(void)
     _glfw_free(_glfw.wl.clipboardString);
 }
 
+void _glfwSetApplicationIconWayland(int count, const GLFWimage* images)
+{
+    // TODO
+    _glfwInputError(GLFW_FEATURE_UNIMPLEMENTED,
+                    "Wayland: Application icon setting not implemented yet");
+}
+
 #endif // _GLFW_WAYLAND
 

src/wl_platform.h

@@ -441,6 +441,7 @@ typedef struct _GLFWcursorWayland
 GLFWbool _glfwConnectWayland(int platformID, _GLFWplatform* platform);
 int _glfwInitWayland(void);
 void _glfwTerminateWayland(void);
+void _glfwSetApplicationIconWayland(int count, const GLFWimage* images);
 
 GLFWbool _glfwCreateWindowWayland(_GLFWwindow* window, const _GLFWwndconfig* wndconfig, const _GLFWctxconfig* ctxconfig, const _GLFWfbconfig* fbconfig);
 void _glfwDestroyWindowWayland(_GLFWwindow* window);

src/x11_init.c

@@ -1171,6 +1171,7 @@ GLFWbool _glfwConnectX11(int platformID, _GLFWplatform* platform)
         GLFW_PLATFORM_X11,
         _glfwInitX11,
         _glfwTerminateX11,
+        _glfwSetApplicationIconX11,
         _glfwGetCursorPosX11,
         _glfwSetCursorPosX11,
         _glfwSetCursorModeX11,
@@ -1654,5 +1655,12 @@ void _glfwTerminateX11(void)
     }
 }
 
+void _glfwSetApplicationIconX11(int count, const GLFWimage* images)
+{
+    // TODO
+    _glfwInputError(GLFW_FEATURE_UNIMPLEMENTED,
+                    "X11: Application icon setting not implemented yet");
+}
+
 #endif // _GLFW_X11
 

src/x11_platform.h

@@ -900,6 +900,7 @@ typedef struct _GLFWcursorX11
 GLFWbool _glfwConnectX11(int platformID, _GLFWplatform* platform);
 int _glfwInitX11(void);
 void _glfwTerminateX11(void);
+void _glfwSetApplicationIconX11(int count, const GLFWimage* images);
 
 GLFWbool _glfwCreateWindowX11(_GLFWwindow* window, const _GLFWwndconfig* wndconfig, const _GLFWctxconfig* ctxconfig, const _GLFWfbconfig* fbconfig);
 void _glfwDestroyWindowX11(_GLFWwindow* window);

tests/icon.c

@@ -89,6 +89,7 @@ static void set_icon(GLFWwindow* window, int icon_color)
     }
 
     glfwSetWindowIcon(window, 1, &img);
+    glfwSetApplicationIcon(1, &img);
 }
 
 static void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
@@ -107,13 +108,21 @@ static void key_callback(GLFWwindow* window, int key, int scancode, int action,
             break;
         case GLFW_KEY_X:
             glfwSetWindowIcon(window, 0, NULL);
+            glfwSetApplicationIcon(0, NULL);
             break;
     }
 }
 
+static void error_callback(int error_code, const char* description)
+{
+    fprintf(stderr, "Error %i: %s\n", error_code, description);
+}
+
 int main(int argc, char** argv)
 {
     GLFWwindow* window;
+    
+    glfwSetErrorCallback(error_callback);
 
     if (!glfwInit())
     {