ext/RMagick/rmstruct.c in rmagick-2.12.2 vs ext/RMagick/rmstruct.c in rmagick-2.13.1

- old
+ new

@@ -1,12 +1,16 @@ -/* $Id: rmstruct.c,v 1.4 2009/05/13 22:50:40 rmagick Exp $ */ -/*============================================================================\ -| Copyright (C) 2009 by Timothy P. Hunter -| Name: rmstruct.c -| Author: Tim Hunter -| Purpose: Contains various Struct class methods. -\============================================================================*/ +/**************************************************************************//** + * Contains various Struct class methods. + * + * Copyright © 2002 - 2009 by Timothy P. Hunter + * + * Changes since Nov. 2009 copyright © by Benjamin Thomas and Omer Bar-or + * + * @file rmstruct.c + * @version $Id: rmstruct.c,v 1.5 2009/12/20 02:33:34 baror Exp $ + * @author Tim Hunter + ******************************************************************************/ #include "rmagick.h" @@ -19,16 +23,21 @@ static VALUE StyleType_new(StyleType); -/* - Extern: Import_AffineMatrix - Purpose: Given a C AffineMatrix, create the equivalent - AffineMatrix object. - Notes: am = Magick::AffineMatrix.new(sx, rx, ry, sy, tx, ty) -*/ +/** + * Given a C AffineMatrix, create the equivalent AffineMatrix object. + * + * No Ruby usage (internal function) + * + * Notes: + * - am = Magick::AffineMatrix.new(sx, rx, ry, sy, tx, ty) + * + * @param affine the C AffineMatrix + * @return a Ruby AffineMatrix object + */ VALUE Import_AffineMatrix(AffineMatrix *affine) { VALUE argv[6]; @@ -40,15 +49,21 @@ argv[5] = rb_float_new(affine->ty); return rb_class_new_instance(6, argv, Class_AffineMatrix); } -/* - Extern: Export_AffineMatrix - Purpose: Convert a Magick::AffineMatrix object to a AffineMatrix structure. - Notes: If not initialized, the defaults are [sx,rx,ry,sy,tx,ty] = [1,0,0,1,0,0] -*/ +/** + * Convert a Magick::AffineMatrix object to a AffineMatrix structure. + * + * No Ruby usage (internal function) + * + * Notes: + * - If not initialized, the defaults are [sx,rx,ry,sy,tx,ty] = [1,0,0,1,0,0] + * + * @param am The C AffineMatrix to modify + * @param st the Ruby AffineMatrix object + */ void Export_AffineMatrix(AffineMatrix *am, VALUE st) { volatile VALUE values, v; @@ -71,15 +86,18 @@ v = rb_ary_entry(values, 5); am->ty = v == Qnil ? 0.0 : NUM2DBL(v); } -/* - Extern: ChromaticityInfo_new(pp) - Purpose: Create a Magick::ChromaticityInfo object from a - ChromaticityInfo structure. -*/ +/** + * Create a Magick::ChromaticityInfo object from a ChromaticityInfo structure. + * + * No Ruby usage (internal function) + * + * @param ci the C ChromaticityInfo + * @return a Ruby Magick::ChromaticityInfo object + */ VALUE ChromaticityInfo_new(ChromaticityInfo *ci) { volatile VALUE red_primary; volatile VALUE green_primary; @@ -94,15 +112,19 @@ return rb_funcall(Class_Chromaticity, rm_ID_new, 4 , red_primary, green_primary, blue_primary, white_point); } -/* - Extern: Export_ChromaticityInfo - Purpose: Extract the elements from a Magick::ChromaticityInfo - and store in a ChromaticityInfo structure. -*/ +/** + * Extract the elements from a Magick::ChromaticityInfo and store in a + * ChromaticityInfo structure. + * + * No Ruby usage (internal function) + * + * @param ci the C ChromaticityInfo structure to modify + * @param chrom the Ruby Magick::ChromaticityInfo object + */ void Export_ChromaticityInfo(ChromaticityInfo *ci, VALUE chrom) { volatile VALUE chrom_members; volatile VALUE red_primary, green_primary, blue_primary, white_point; @@ -155,14 +177,19 @@ ci->white_point.y = y == Qnil ? 0.0 : NUM2DBL(y); ci->white_point.z = 0.0; } -/* - Method: Magick::Chromaticity#to_s - Purpose: Create a string representation of a Magick::Chromaticity -*/ +/** + * Create a string representation of a Magick::Chromaticity. + * + * Ruby usage: + * - @verbatim Magick::Chromaticity#to_s @endverbatim + * + * @param self this object + * @return the string + */ VALUE ChromaticityInfo_to_s(VALUE self) { ChromaticityInfo ci; char buff[200]; @@ -178,14 +205,18 @@ ci.white_point.x, ci.white_point.y); return rb_str_new2(buff); } -/* - External: Import_ColorInfo - Purpose: Convert a ColorInfo structure to a Magick::Color -*/ +/** + * Convert a ColorInfo structure to a Magick::Color. + * + * No Ruby usage (internal function) + * + * @param ci the C ColorInfo structure + * @return a Ruby Magick::Color object + */ VALUE Import_ColorInfo(const ColorInfo *ci) { ComplianceType compliance_type; volatile VALUE name; @@ -201,14 +232,18 @@ return rb_funcall(Class_Color, rm_ID_new, 3 , name, compliance, color); } -/* - External: Export_ColorInfo - Purpose: Convert a Magick::Color to a ColorInfo structure -*/ +/** + * Convert a Magick::Color to a ColorInfo structure. + * + * No Ruby usage (internal function) + * + * @param ci the C ColorInfo structure to modify + * @param st the Ruby Magick::Color object + */ void Export_ColorInfo(ColorInfo *ci, VALUE st) { Pixel *pixel; volatile VALUE members, m; @@ -247,16 +282,22 @@ ci->color.index = (MagickRealType) 0; } } -/* - Extern: Color_to_MagickPixelPacket - Purpose: Convert either a String color name or - a Magick::Pixel to a MagickPixelPacket - Notes: The channel values in a MagickPixelPacket are doubles. -*/ +/** + * Convert either a String color name or a Magick::Pixel to a MagickPixelPacket. + * + * No Ruby usage (internal function) + * + * Notes: + * - The channel values in a MagickPixelPacket are doubles. + * + * @param image the Image + * @param mpp The MagickPixelPacket to modify + * @param color the name of the color + */ void Color_to_MagickPixelPacket(Image *image, MagickPixelPacket *mpp, VALUE color) { PixelPacket pp; @@ -270,26 +311,35 @@ mpp->blue = (MagickRealType) pp.blue; mpp->opacity = (MagickRealType) pp.opacity; } -/* - Static: destroy_ColorInfo - Purpose: free the storage allocated by Export_ColorInfo, above. -*/ +/** + * Free the storage allocated by Export_ColorInfo. + * + * No Ruby usage (internal function) + * + * @param ci the ColorInfo object + * @see Export_ColorInfo + */ static void destroy_ColorInfo(ColorInfo *ci) { magick_free((void*)ci->name); ci->name = NULL; } -/* - Method: Color#to_s - Purpose: Return a string representation of a Magick::Color object -*/ +/** + * Return a string representation of a Magick::Color object. + * + * Ruby usage: + * - @verbatim Color#to_s @endverbatim + * + * @param self this object + * @return the string + */ VALUE Color_to_s(VALUE self) { ColorInfo ci; char buff[1024]; @@ -309,17 +359,23 @@ destroy_ColorInfo(&ci); return rb_str_new2(buff); } -/* - Static: ComplianceType_name - Purpose: Return the string representation of a ComplianceType value - Notes: xMagick will OR multiple compliance types so we have to - arbitrarily pick one name. Set the compliance argument - to the selected value. -*/ +/** + * Return the string representation of a ComplianceType value. + * + * No Ruby usage (internal function) + * + * Notes: + * - xMagick will OR multiple compliance types so we have to arbitrarily pick + * one name. + * - Set the compliance argument to the selected value. + * + * @param c the ComplianceType value + * @return the string + */ static const char * ComplianceType_name(ComplianceType *c) { if ((*c & (SVGCompliance|X11Compliance|XPMCompliance)) == (SVGCompliance|X11Compliance|XPMCompliance)) @@ -352,14 +408,18 @@ return "UndefinedCompliance"; } } -/* - * Static: ComplianceType_new - Purpose: construct a ComplianceType enum object for the specified value -*/ +/** + * Construct a ComplianceType enum object for the specified value. + * + * No Ruby usage (internal function) + * + * @param compliance the C ComplianceType value + * @return the Ruby ComplianceType enum object + */ static VALUE ComplianceType_new(ComplianceType compliance) { const char *name; @@ -368,14 +428,18 @@ name = ComplianceType_name(&compliance); return rm_enum_new(Class_ComplianceType, ID2SYM(rb_intern(name)), INT2FIX(compliance)); } -/* - External: Import_TypeInfo - Purpose: Convert a TypeInfo structure to a Magick::Font -*/ +/** + * Convert a TypeInfo structure to a Magick::Font. + * + * No Ruby usage (internal function) + * + * @param ti the C TypeInfo structure + * @return a Ruby Magick::Font object + */ VALUE Import_TypeInfo(const TypeInfo *ti) { volatile VALUE name, description, family; volatile VALUE style, stretch, weight; @@ -395,14 +459,18 @@ , name, description, family, style , stretch, weight, encoding, foundry, format); } -/* - External: Export_TypeInfo - Purpose: Convert a Magick::Font to a TypeInfo structure -*/ +/** + * Convert a Magick::Font to a TypeInfo structure. + * + * No Ruby usage (internal function) + * + * @param ti the C TypeInfo structure to modify + * @param st the Ruby Magick::Font object + */ void Export_TypeInfo(TypeInfo *ti, VALUE st) { volatile VALUE members, m; @@ -444,14 +512,18 @@ if (m != Qnil) (void) CloneString((char **)&(ti->format), StringValuePtr(m)); } -/* - Static: destroy_TypeInfo - Purpose: free the storage allocated by Export_TypeInfo, above. -*/ +/** + * Free the storage allocated by Export_TypeInfo. + * + * No Ruby usage (internal function) + * + * @param ti the TypeInfo object + * @see Export_TypeInfo + */ static void destroy_TypeInfo(TypeInfo *ti) { magick_free((void*)ti->name); ti->name = NULL; @@ -466,14 +538,18 @@ magick_free((void*)ti->format); ti->format = NULL; } -/* - External: Font_to_s - Purpose: implement the Font#to_s method -*/ +/** + * Implement the Font#to_s method. + * + * No Ruby usage (internal function) + * + * @param self this object + * @return the string + */ VALUE Font_to_s(VALUE self) { TypeInfo ti; char weight[20]; @@ -511,26 +587,34 @@ return rb_str_new2(buff); } -/* - Extern: Import_PointInfo(pp) - Purpose: Create a Magick::Point object from a PointInfo structure. -*/ +/** + * Create a Magick::Point object from a PointInfo structure. + * + * No Ruby usage (internal function) + * + * @param p the C PointInfo structure + * @return a Ruby Magick::Point object + */ VALUE Import_PointInfo(PointInfo *p) { return rb_funcall(Class_Point, rm_ID_new, 2 , INT2FIX(p->x), INT2FIX(p->y)); } -/* - Extern: Export_PointInfo - Purpose: Convert a Magick::Point object to a PointInfo structure -*/ +/** + * Convert a Magick::Point object to a PointInfo structure. + * + * No Ruby usage (internal function) + * + * @param pi the C PointInfo structure to modify + * @param sp the Ruby Magick::Point object + */ void Export_PointInfo(PointInfo *pi, VALUE sp) { volatile VALUE members, m; @@ -545,26 +629,34 @@ m = rb_ary_entry(members, 1); pi->y = m == Qnil ? 0.0 : NUM2DBL(m); } -/* - Extern: Import_PrimaryInfo(pp) - Purpose: Create a Magick::PrimaryInfo object from a PrimaryInfo structure. -*/ +/** + * Create a Magick::PrimaryInfo object from a PrimaryInfo structure. + * + * No Ruby usage (internal function) + * + * @param p the C PrimaryInfo structure + * @return a Ruby Magick::PrimaryInfo object + */ VALUE Import_PrimaryInfo(PrimaryInfo *p) { return rb_funcall(Class_Primary, rm_ID_new, 3 , INT2FIX(p->x), INT2FIX(p->y), INT2FIX(p->z)); } -/* - Extern: Export_PrimaryInfo - Purpose: Convert a Magick::PrimaryInfo object to a PrimaryInfo structure -*/ +/** + * Convert a Magick::PrimaryInfo object to a PrimaryInfo structure. + * + * No Ruby usage (internal function) + * + * @param pi the C PrimaryInfo structure to modify + * @param sp the Ruby Magick::PrimaryInfo object + */ void Export_PrimaryInfo(PrimaryInfo *pi, VALUE sp) { volatile VALUE members, m; @@ -581,14 +673,19 @@ m = rb_ary_entry(members, 2); pi->z = m == Qnil ? 0.0 : NUM2DBL(m); } -/* - Method: Magick::PrimaryInfo#to_s - Purpose: Create a string representation of a Magick::PrimaryInfo -*/ +/** + * Create a string representation of a Magick::PrimaryInfo. + * + * Ruby usage: + * - @verbatim Magick::PrimaryInfo#to_s @endverbatim + * + * @param self this object + * @return the string + */ VALUE PrimaryInfo_to_s(VALUE self) { PrimaryInfo pi; char buff[100]; @@ -597,14 +694,18 @@ sprintf(buff, "x=%g, y=%g, z=%g", pi.x, pi.y, pi.z); return rb_str_new2(buff); } -/* - External: Import_RectangleInfo - Purpose: Convert a RectangleInfo structure to a Magick::Rectangle -*/ +/** + * Convert a RectangleInfo structure to a Magick::Rectangle. + * + * No Ruby usage (internal function) + * + * @param rect the C RectangleInfo structure + * @return a Ruby Magick::Rectangle object + */ VALUE Import_RectangleInfo(RectangleInfo *rect) { volatile VALUE width; volatile VALUE height; @@ -617,14 +718,18 @@ return rb_funcall(Class_Rectangle, rm_ID_new, 4 , width, height, x, y); } -/* - External: Export_RectangleInfo - Purpose: Convert a Magick::Rectangle to a RectangleInfo structure. -*/ +/** + * Convert a Magick::Rectangle to a RectangleInfo structure. + * + * No Ruby usage (internal function) + * + * @param rect the C RectangleInfo structure to modify + * @param sr the Ruby Magick::Rectangle object + */ void Export_RectangleInfo(RectangleInfo *rect, VALUE sr) { volatile VALUE members, m; @@ -643,14 +748,19 @@ m = rb_ary_entry(members, 3); rect->y = m == Qnil ? 0 : NUM2LONG (m); } -/* - Method: Magick::Rectangle#to_s - Purpose: Create a string representation of a Magick::Rectangle -*/ +/** + * Create a string representation of a Magick::Rectangle. + * + * Ruby usage: + * - @verbatim Magick::Rectangle#to_s @endverbatim + * + * @param self this object + * @return the string + */ VALUE RectangleInfo_to_s(VALUE self) { RectangleInfo rect; char buff[100]; @@ -660,14 +770,18 @@ , rect.width, rect.height, rect.x, rect.y); return rb_str_new2(buff); } -/* - External: Import_SegmentInfo - Purpose: Convert a SegmentInfo structure to a Magick::Segment -*/ +/** + * Convert a SegmentInfo structure to a Magick::Segment. + * + * No Ruby usage (internal function) + * + * @param segment the C SegmentInfo structure + * @return a Ruby Magick::Segment object + */ VALUE Import_SegmentInfo(SegmentInfo *segment) { volatile VALUE x1, y1, x2, y2; @@ -677,14 +791,18 @@ y2 = rb_float_new(segment->y2); return rb_funcall(Class_Segment, rm_ID_new, 4, x1, y1, x2, y2); } -/* - External: Export_SegmentInfo - Purpose: Convert a Magick::Segment to a SegmentInfo structure. -*/ +/** + * Convert a Magick::Segment to a SegmentInfo structure. + * + * No Ruby usage (internal function) + * + * @param segment the C SegmentInfo structure to modify + * @param s the Ruby Magick::Segment object + */ void Export_SegmentInfo(SegmentInfo *segment, VALUE s) { volatile VALUE members, m; @@ -704,14 +822,19 @@ m = rb_ary_entry(members, 3); segment->y2 = m == Qnil ? 0.0 : NUM2DBL(m); } -/* - Method: Magick::SegmentInfo#to_s - Purpose: Create a string representation of a Magick::Segment -*/ +/** + * Create a string representation of a Magick::Segment. + * + * Ruby usage: + * - @verbatim Magick::SegmentInfo#to_s @endverbatim + * + * @param self this object + * @return the string + */ VALUE SegmentInfo_to_s(VALUE self) { SegmentInfo segment; char buff[100]; @@ -721,14 +844,18 @@ , segment.x1, segment.y1, segment.x2, segment.y2); return rb_str_new2(buff); } -/* - Static: StretchType_name - Purpose: Return the string representation of a StretchType value -*/ +/** + * Return the string representation of a StretchType value. + * + * No Ruby usage (internal function) + * + * @param stretch the StretchType value + * @return the string + */ static const char * StretchType_name(StretchType stretch) { switch (stretch) { @@ -747,26 +874,34 @@ return "UndefinedStretch"; } -/* - Static: StretchType_new - Purpose: Construct a StretchType enum for a specified StretchType value -*/ +/** + * Construct a StretchType enum for a specified StretchType value. + * + * No Ruby usage (internal function) + * + * @param stretch the C StretchType value + * @return a Ruby StretchType enum + */ static VALUE StretchType_new(StretchType stretch) { const char *name = StretchType_name(stretch); return rm_enum_new(Class_StretchType, ID2SYM(rb_intern(name)), INT2FIX(stretch)); } -/* - Static: StyleType_name - Purpose: Return the string representation of a StyleType value -*/ +/** + * Return the string representation of a StyleType value. + * + * No Ruby usage (internal function) + * + * @param style the StyleType value + * @return the string + */ static const char * StyleType_name(StyleType style) { switch (style) { @@ -779,26 +914,34 @@ return "UndefinedStyle"; } -/* - Static: StyleType_new - Purpose: Construct a StyleType enum for a specified StyleType value -*/ +/** + * Construct a StyleType enum for a specified StyleType value. + * + * No Ruby usage (internal function) + * + * @param style the C StyleType value + * @return a Ruby StyleType enum + */ static VALUE StyleType_new(StyleType style) { const char *name = StyleType_name(style); return rm_enum_new(Class_StyleType, ID2SYM(rb_intern(name)), INT2FIX(style)); } -/* - External: Import_TypeMetric - Purpose: Convert a TypeMetric structure to a Magick::TypeMetric -*/ +/** + * Convert a TypeMetric structure to a Magick::TypeMetric. + * + * No Ruby usage (internal function) + * + * @param tm the C TypeMetric structure + * @return a Ruby Magick::TypeMetric object + */ VALUE Import_TypeMetric(TypeMetric *tm) { volatile VALUE pixels_per_em; volatile VALUE ascent, descent; @@ -820,14 +963,18 @@ , height, max_advance, bounds , underline_position, underline_thickness); } -/* - External: Export_TypeMetric - Purpose: Convert a Magick::TypeMetric to a TypeMetric structure. -*/ +/** + * Convert a Magick::TypeMetric to a TypeMetric structure. + * + * No Ruby usage (internal function) + * + * @param tm the C TypeMetric structure to modify + * @param st the Ruby Magick::TypeMetric object + */ void Export_TypeMetric(TypeMetric *tm, VALUE st) { volatile VALUE members, m; volatile VALUE pixels_per_em; @@ -861,13 +1008,18 @@ m = rb_ary_entry(members, 8); tm->underline_thickness = m == Qnil ? 0.0 : NUM2DBL(m); } -/* - Method: Magick::TypeMetric#to_s - Purpose: Create a string representation of a Magick::TypeMetric -*/ +/** + * Create a string representation of a Magick::TypeMetric. + * + * Ruby usage: + * - @verbatim Magick::TypeMetric#to_s @endverbatim + * + * @param self this object + * @return the string + */ VALUE TypeMetric_to_s(VALUE self) { volatile VALUE str; TypeMetric tm;