rmagick 3.2.0 → 4.3.0

data/ext/RMagick/rmmontage.c

@@ -22,7 +22,7 @@
  * No Ruby usage (internal function)
  *
  * Notes:
- *   - If the Magick::Montage#texture method wrote a texture file, the file is
+ *   - If the Magick::ImageList::Montage#texture method wrote a texture file, the file is
  *     deleted here.
  *
  * @param obj the montage object
@@ -41,7 +41,7 @@ destroy_Montage(void *obj)
     }
     if (montage->info)
     {
-        (void) DestroyMontageInfo(montage->info);
+        DestroyMontageInfo(montage->info);
         montage->info = NULL;
     }
     xfree(montage);
@@ -51,11 +51,7 @@ destroy_Montage(void *obj)
 /**
  * Create a new Montage object.
  *
- * Ruby usage:
- *   - @verbatim Montage.new @endverbatim
- *
- * @param class the Ruby class to use
- * @return a new Montage object
+ * @return [Magick::ImageList::Montage] a new Montage object
  */
 VALUE
 Montage_alloc(VALUE class)
@@ -73,11 +69,11 @@ Montage_alloc(VALUE class)
     }
 
     montage_info = CloneMontageInfo(image_info, NULL);
-    (void) (void) DestroyImageInfo(image_info);
+    (void) DestroyImageInfo(image_info);
 
     if (!montage_info)
     {
-        rb_raise(rb_eNoMemError, "not enough memory to initialize Magick::Montage object");
+        rb_raise(rb_eNoMemError, "not enough memory to initialize Magick::ImageList::Montage object");
     }
 
     montage = ALLOC(Montage);
@@ -94,12 +90,8 @@ Montage_alloc(VALUE class)
 /**
  * Set background_color value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#background_color(color-name) @endverbatim
- *
- * @param self this object
- * @param color the color name
- * @return color
+ * @param color [Magick::Pixel, String] the color name
+ * @return [Magick::Pixel, String] the given color name
  */
 VALUE
 Montage_background_color_eq(VALUE self, VALUE color)
@@ -115,12 +107,8 @@ Montage_background_color_eq(VALUE self, VALUE color)
 /**
  * Set border_color value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#border_color(color-name) @endverbatim
- *
- * @param self this object
- * @param color the color name
- * @return color
+ * @param color [Magick::Pixel, String] the color name
+ * @return [Magick::Pixel, String] the given color name
  */
 VALUE
 Montage_border_color_eq(VALUE self, VALUE color)
@@ -136,12 +124,8 @@ Montage_border_color_eq(VALUE self, VALUE color)
 /**
  * Set border_width value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#border_width(width) @endverbatim
- *
- * @param self this object
- * @param width the width
- * @return width
+ * @param width [Numeric] the width
+ * @return [Numeric] the given width
  */
 VALUE
 Montage_border_width_eq(VALUE self, VALUE width)
@@ -157,12 +141,8 @@ Montage_border_width_eq(VALUE self, VALUE width)
 /**
  * Set a composition operator.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#compose(width) @endverbatim
- *
- * @param self this object
- * @param compose the composition operator
- * @return compose
+ * @param compose [Magick::CompositeOperator] the composition operator
+ * @return [Magick::CompositeOperator] the given compose operator
  */
 VALUE
 Montage_compose_eq(VALUE self, VALUE compose)
@@ -178,12 +158,8 @@ Montage_compose_eq(VALUE self, VALUE compose)
 /**
  * Set filename value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#filename(name) @endverbatim
- *
- * @param self this object
- * @param filename the filename
- * @return filename
+ * @param filename [String] the filename
+ * @return [String] filename
  */
 VALUE
 Montage_filename_eq(VALUE self, VALUE filename)
@@ -191,7 +167,7 @@ Montage_filename_eq(VALUE self, VALUE filename)
     Montage *montage;
 
     Data_Get_Struct(self, Montage, montage);
-    strncpy(montage->info->filename, StringValuePtr(filename), MaxTextExtent-1);
+    strlcpy(montage->info->filename, StringValueCStr(filename), sizeof(montage->info->filename));
     return filename;
 }
 
@@ -199,12 +175,8 @@ Montage_filename_eq(VALUE self, VALUE filename)
 /**
  * Set fill value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#fill(color-name) @endverbatim
- *
- * @param self this object
- * @param color the color name
- * @return color
+ * @param color [Magick::Pixel, String] the color name
+ * @return [Magick::Pixel, String] the given color name
  */
 VALUE
 Montage_fill_eq(VALUE self, VALUE color)
@@ -220,12 +192,8 @@ Montage_fill_eq(VALUE self, VALUE color)
 /**
  * Set font value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#font(font-name) @endverbatim
- *
- * @param self this object
- * @param font the font name
- * @return font
+ * @param font [String] the font name
+ * @return [String] the given font name
  */
 VALUE
 Montage_font_eq(VALUE self, VALUE font)
@@ -233,7 +201,7 @@ Montage_font_eq(VALUE self, VALUE font)
     Montage *montage;
 
     Data_Get_Struct(self, Montage, montage);
-    magick_clone_string(&montage->info->font, StringValuePtr(font));
+    magick_clone_string(&montage->info->font, StringValueCStr(font));
 
     return font;
 }
@@ -242,17 +210,12 @@ Montage_font_eq(VALUE self, VALUE font)
 /**
  * Set frame value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#frame(frame-geometry) @endverbatim
- *
- * Notes:
- *   - The geometry is a string in the form:
- *     @verbatim <width>x<height>+<outer-bevel-width>+<inner-bevel-width> @endverbatim
- *     or a Geometry object
+ * - The geometry is a string in the form:
+ *      <width>x<height>+<outer-bevel-width>+<inner-bevel-width>
+ *   or a Geometry object
  *
- * @param self this object
- * @param frame_arg the frame geometry
- * @return frame_arg
+ * @param frame_arg [String] the frame geometry
+ * @see https://www.imagemagick.org/Magick++/Geometry.html
  */
 VALUE
 Montage_frame_eq(VALUE self, VALUE frame_arg)
@@ -261,8 +224,8 @@ Montage_frame_eq(VALUE self, VALUE frame_arg)
     VALUE frame;
 
     Data_Get_Struct(self, Montage, montage);
-    frame = rm_to_s(frame_arg);
-    magick_clone_string(&montage->info->frame, StringValuePtr(frame));
+    frame = rb_String(frame_arg);
+    magick_clone_string(&montage->info->frame, StringValueCStr(frame));
 
     RB_GC_GUARD(frame);
 
@@ -273,12 +236,13 @@ Montage_frame_eq(VALUE self, VALUE frame_arg)
 /**
  * Set geometry value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#geometry(geometry) @endverbatim
+ * - The geometry is a string in the form:
+ *      <width>x<height>+<outer-bevel-width>+<inner-bevel-width>
+ *   or a Geometry object
  *
- * @param self this object
- * @param geometry_arg the geometry
- * @return geometry_arg
+ * @param geometry_arg [String] the geometry
+ * @return [String] the given geometry
+ * @see https://www.imagemagick.org/Magick++/Geometry.html
  */
 VALUE
 Montage_geometry_eq(VALUE self, VALUE geometry_arg)
@@ -287,8 +251,8 @@ Montage_geometry_eq(VALUE self, VALUE geometry_arg)
     VALUE geometry;
 
     Data_Get_Struct(self, Montage, montage);
-    geometry = rm_to_s(geometry_arg);
-    magick_clone_string(&montage->info->geometry, StringValuePtr(geometry));
+    geometry = rb_String(geometry_arg);
+    magick_clone_string(&montage->info->geometry, StringValueCStr(geometry));
 
     RB_GC_GUARD(geometry);
 
@@ -299,12 +263,8 @@ Montage_geometry_eq(VALUE self, VALUE geometry_arg)
 /**
  * Set gravity value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#gravity(gravity-type) @endverbatim
- *
- * @param self this object
- * @param gravity the gravity type
- * @return gravity
+ * @param gravity [Magick::GravityType] the gravity type
+ * @return [Magick::GravityType] the given gravity
  */
 VALUE
 Montage_gravity_eq(VALUE self, VALUE gravity)
@@ -320,11 +280,7 @@ Montage_gravity_eq(VALUE self, VALUE gravity)
 /**
  * Initialize a Montage object. Does nothing currently.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#initialize @endverbatim
- *
- * @param self this object
- * @return self
+ * @return [Magick::ImageList::Montage] self
  */
 VALUE
 Montage_initialize(VALUE self)
@@ -337,12 +293,8 @@ Montage_initialize(VALUE self)
 /**
  * Set matte_color value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#matte_color(color-name) @endverbatim
- *
- * @param self this object
- * @param color the color name
- * @return color
+ * @param color [Magick::Pixel, String] the color name
+ * @return [Magick::Pixel, String] the given color name
  */
 VALUE
 Montage_matte_color_eq(VALUE self, VALUE color)
@@ -358,12 +310,8 @@ Montage_matte_color_eq(VALUE self, VALUE color)
 /**
  * Set pointsize value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#pointsize= @endverbatim
- *
- * @param self this object
- * @param size the point size
- * @return size
+ * @param size [Numeric] the point size
+ * @return [Numeric] the given point size
  */
 VALUE
 Montage_pointsize_eq(VALUE self, VALUE size)
@@ -379,12 +327,8 @@ Montage_pointsize_eq(VALUE self, VALUE size)
 /**
  * Set shadow value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#shadow= @endverbatim
- *
- * @param self this object
- * @param shadow the shadow
- * @return shadow
+ * @param shadow [Bool] true if the shadow will be enabled
+ * @return [Bool] the given value
  */
 VALUE
 Montage_shadow_eq(VALUE self, VALUE shadow)
@@ -400,12 +344,8 @@ Montage_shadow_eq(VALUE self, VALUE shadow)
 /**
  * Set stroke value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#stroke(color-name) @endverbatim
- *
- * @param self this object
- * @param color the color name
- * @return self
+ * @param color [Magick::Pixel, String] the color name
+ * @return [Magick::Pixel, String] the given color name
  */
 VALUE
 Montage_stroke_eq(VALUE self, VALUE color)
@@ -421,12 +361,9 @@ Montage_stroke_eq(VALUE self, VALUE color)
 /**
  * Set texture value.
  *
- * Ruby usage:
- *   - @verbatim Montage#texture(texture-image) @endverbatim
- *
- * @param self this object
- * @param texture the texture image
- * @return texture
+ * @param texture [Magick::Image, Magick::ImageList] Either an imagelist or an image. If an
+ *   imagelist, uses the current image.
+ * @return [Magick::Image] the given texture image
  */
 VALUE
 Montage_texture_eq(VALUE self, VALUE texture)
@@ -450,7 +387,7 @@ Montage_texture_eq(VALUE self, VALUE texture)
     texture_image = rm_check_destroyed(texture);
 
     // Write a temp copy of the image & save its name.
-    rm_write_temp_image(texture_image, temp_name);
+    rm_write_temp_image(texture_image, temp_name, sizeof(temp_name));
     magick_clone_string(&montage->info->texture, temp_name);
 
     return texture;
@@ -460,12 +397,13 @@ Montage_texture_eq(VALUE self, VALUE texture)
 /**
  * Set tile value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#tile(tile) @endverbatim
+ * - The geometry is a string in the form:
+ *      <width>x<height>+<outer-bevel-width>+<inner-bevel-width>
+ *   or a Geometry object
  *
- * @param self this object
- * @param tile_arg the tile
- * @return tile_arg
+ * @param tile_arg [String] the tile geometry
+ * @return [String] the given tile geometry
+ * @see https://www.imagemagick.org/Magick++/Geometry.html
  */
 VALUE
 Montage_tile_eq(VALUE self, VALUE tile_arg)
@@ -474,8 +412,8 @@ Montage_tile_eq(VALUE self, VALUE tile_arg)
     VALUE tile;
 
     Data_Get_Struct(self, Montage, montage);
-    tile = rm_to_s(tile_arg);
-    magick_clone_string(&montage->info->tile, StringValuePtr(tile));
+    tile = rb_String(tile_arg);
+    magick_clone_string(&montage->info->tile, StringValueCStr(tile));
 
     RB_GC_GUARD(tile);
 
@@ -486,12 +424,8 @@ Montage_tile_eq(VALUE self, VALUE tile_arg)
 /**
  * Set title value.
  *
- * Ruby usage:
- *   - @verbatim Magick::Montage#title(title) @endverbatim
- *
- * @param self this object
- * @param title the title
- * @return title
+ * @param title [String] the title
+ * @return [String] the given title
  */
 VALUE
 Montage_title_eq(VALUE self, VALUE title)
@@ -499,17 +433,17 @@ Montage_title_eq(VALUE self, VALUE title)
     Montage *montage;
 
     Data_Get_Struct(self, Montage, montage);
-    magick_clone_string(&montage->info->title, StringValuePtr(title));
+    magick_clone_string(&montage->info->title, StringValueCStr(title));
     return title;
 }
 
 
 /**
- * Return a new Magick::Montage object.
+ * Return a new Magick::ImageList::Montage object.
  *
  * No Ruby usage (internal function)
  *
- * @return a new Magick::Montage object
+ * @return a new Magick::ImageList::Montage object
  */
 VALUE
 rm_montage_new(void)