add Image#get_gainmap

Add get_gainmap, the `gainmap` flag for keep, and a test.

Author: jcupitt

CHANGELOG.md

@@ -4,7 +4,8 @@
 
 * move library_name out of the global namespace and into FFI [jcupitt]
 * update docs for libvips 8.18 [jcupitt]
-* version bump to 2.3 ready for upcoming gainmap API
+* add Image#get_gainmap [jcupitt]
+* version bump to 2.3
 
 ## Version 2.2.5 (2025-08-20)
 

lib/vips/foreign_keep.rb

@@ -6,6 +6,7 @@ module Vips
   # *   `:xmp` keep XMP metadata
   # *   `:iptc` keep IPTC metadata
   # *   `:icc` keep ICC profiles
+  # *   `:gainmap` keep the gainmap metadata
   # *   `:other` keep other metadata
 
   class ForeignKeep < Symbol

lib/vips/image.rb

@@ -50,6 +50,10 @@ module Vips
     attach_function :vips_addalpha, [:pointer, :pointer, :varargs], :int
   end
 
+  if Vips.at_least_libvips?(8, 18)
+    attach_function :vips_image_get_gainmap, [:pointer], :pointer
+  end
+
   # move these three lines to mutableimage when we finally remove set and
   # remove in this class
   attach_function :vips_image_set,
@@ -797,8 +801,36 @@ def get_fields
       names
     end
 
+    # Get the gainmap (if any) from an image.
+    #
+    # After modifying the gainmap, you should write it back to the image in a
+    # mutable block, see [#mutate], in the field "gainmap".
+    #
+    # For example:
+    #
+    # ```ruby
+    # gainmap = image.get_gainmap
+    # unless gainmap.nil?
+    #   new_gainmap = gainmap.crop left, top, width, height
+    #   image = image.mutate do |x|
+    #     x.set_type! Vips::IMAGE_TYPE, "gainmap", new_gainmap
+    #   end
+    # end
+    # ```
+    #
+    # @return [Image] the gainmap image, or nil
+    def get_gainmap
+      if Vips.at_least_libvips?(8, 18)
+        vi = Vips.vips_image_get_gainmap self
+        return nil if vi.null?
+        Image.new(vi)
+      else
+        nil
+      end
+    end
+
     # Mutate an image with a block. Inside the block, you can call methods
-    # which modify the image, such as setting or removing metadata, or
+    # which modify the image, such as setting or removing metadata or
     # modifying pixels.
     #
     # For example:

spec/image_spec.rb

@@ -726,6 +726,27 @@
     end
   end
 
+  # added in 8.18
+  if Vips.respond_to? :vips_image_get_gainmap
+    it "can modify gainmaps" do
+      image = Vips::Image.new_from_file simg "ultra-hdr.jpg"
+      # test the example code in image.rb doc comment for get_gainmap
+      gainmap = image.get_gainmap
+      unless gainmap.nil?
+        new_gainmap = gainmap.crop 0, 0, 10, 10
+        image = image.mutate do |x|
+          x.set_type! Vips::IMAGE_TYPE, "gainmap", new_gainmap
+        end
+  
+        buffer = image.write_to_buffer ".jpg"
+        image = Vips::Image.new_from_buffer buffer, ""
+        new_gainmap2 = image.get_gainmap
+  
+        expect(new_gainmap2.width).to eq(10)
+      end
+    end
+  end
+
   it "can has_alpha?" do
     x = Vips::Image.new_from_file "./spec/samples/alpha.png"
     expect(x.has_alpha?).to be true