Merge pull request #10727 from electron/named-nativeimage

Add an API to get a nativeImage from a named NSImage

docs/api/native-image.md

@@ -157,6 +157,34 @@ Returns `NativeImage`
 
 Creates a new `NativeImage` instance from `dataURL`.
 
+### `nativeImage.createFromNamedImage(imageName[, hslShift])` _macOS_
+
+* `imageName` String
+* `hslShift` Number[]
+
+Returns `NativeImage`
+
+Creates a new `NativeImage` instance from the NSImage that maps to the
+given image name.  See [`NSImageName`](https://developer.apple.com/documentation/appkit/nsimagename?language=objc)
+for a list of possible values.
+
+The `hslShift` is applied to the image with the following rules
+* `hsl_shift[0]` (hue): The absolute hue value for the image - 0 and 1 map
+     to 0 and 360 on the hue color wheel (red).
+* `hsl_shift[1]` (saturation): A saturation shift for the image, with the
+    following key values:  
+    0 = remove all color.  
+    0.5 = leave unchanged.  
+    1 = fully saturate the image.  
+* `hsl_shift[2]` (lightness): A lightness shift for the image, with the
+    following key values:  
+    0 = remove all lightness (make all pixels black).  
+    0.5 = leave unchanged.  
+    1 = full lightness (make all pixels white).
+
+This means that `[-1, 0, 1]` will make the image completely white and
+`[-1, 1, 0]` will make the image completely black.
+
 ## Class: NativeImage
 
 > Natively wrap images such as tray, dock, and application icons.