basis/math/vectors/conversion/conversion-docs.factor

   1 ! (c)2009 Joe Groff bsd license
   2 USING: classes help.markup help.syntax kernel quotations ;
   3 IN: math.vectors.conversion
   4
   5 HELP: bad-vconvert
   6 { $values
   7     { "from-type" "a SIMD type" } { "to-type" "a SIMD type" }
   8 }
   9 { $description "This error is thrown when " { $link vconvert } " is given two SIMD types it cannot directly convert." } ;
  10
  11 HELP: bad-vconvert-input
  12 { $values
  13     { "value" object } { "expected-type" class }
  14 }
  15 { $description "This error is thrown when an input to " { $link vconvert } " does not match the expected " { $snippet "from-type" } "." } ;
  16
  17 { bad-vconvert bad-vconvert-input } related-words
  18
  19 HELP: vconvert
  20 { $values
  21     { "from-type" "a SIMD type" } { "to-type" "a SIMD type" }
  22 }
  23 { $description "Converts SIMD vectors of " { $snippet "from-type" } " to " { $snippet "to-type" } ". The number of inputs and outputs depends on the relationship of the two types:"
  24 { $list
  25 { "If " { $snippet "to-type" } " is a floating-point vector type with the same byte length and element count as the integer vector type " { $snippet "from-type" } " (for example, from " { $snippet "int-8" } " to " { $snippet "float-8" } " or from " { $snippet "longlong-2" } " to " { $snippet "double-2" } "), " { $snippet "vconvert" } " takes one vector of " { $snippet "from-type" } " and converts its elements to floating-point, outputting one vector of " { $snippet "to-type" } "." }
  26 { "Likewise, if " { $snippet "to-type" } " is an integer vector type with the same byte length and element count as the floating-point vector type " { $snippet "from-type" } ", " { $snippet "vconvert" } " takes one vector of " { $snippet "from-type" } " and truncates its elements to integers, outputting one vector of " { $snippet "to-type" } "." }
  27 { "If " { $snippet "to-type" } " is a vector type with the same byte length as and twice the element count of the vector type " { $snippet "from-type" } " (for example, from " { $snippet "int-4" } " to " { $snippet "ushort-8" } ", from " { $snippet "double-2" } " to " { $snippet "float-4" } ", or from " { $snippet "short-8" } " to " { $snippet "char-16" } "), " { $snippet "vconvert" } " takes two vectors of " { $snippet "from-type" } " and packs them into one vector of " { $snippet "to-type" } ", saturating values too large or small to be representable as elements of " { $snippet "to-type" } "." }
  28 { "If " { $snippet "to-type" } " is a vector type with the same byte length as and half the element count of the vector type " { $snippet "from-type" } " (for example, from " { $snippet "ushort-8" } " to " { $snippet "int-4" } ", from " { $snippet "float-4" } " to " { $snippet "double-2" } ", or from " { $snippet "char-16" } " to " { $snippet "short-8" } "), " { $snippet "vconvert" } " takes one vector of " { $snippet "from-type" } " and unpacks it into two vectors of " { $snippet "to-type" } "." }
  29 }
  30 { $snippet "from-type" } " and " { $snippet "to-type" } " must adhere to the following restrictions; a " { $link bad-vconvert } " error will be thrown otherwise:"
  31 { $list
  32 { { $snippet "from-type" } " and " { $snippet "to-type" } " must have the same byte length. You cannot currently convert between 128- and 256-bit vector types." }
  33 { "For conversions between floating-point and integer vectors, " { $snippet "from-type" } " and " { $snippet "to-type" } " must have the same element length." }
  34 { "For packing conversions, " { $snippet "from-type" } " and " { $snippet "to-type" } " must be both floating-point or both integer types. Integer types can be packed from signed to unsigned or from unsigned to unsigned types. Unsigned to signed packing is invalid." }
  35 { "For unpacking conversions, " { $snippet "from-type" } " and " { $snippet "to-type" } " must be both floating-point or both integer types. Integer types can be unpacked from unsigned to signed or from unsigned to unsigned types. Signed to unsigned unpacking is invalid." }
  36 }
  37 }
  38 { $examples
  39 "Conversion between integer and float vectors:"
  40 { $example """USING: alien.c-types math.vectors.conversion math.vectors.simd
  41 prettyprint ;
  42 SIMDS: int float longlong double ;
  43
  44 int-8{ 0 1 2 3 4 5 6 7 } int-8 float-8 vconvert .
  45 double-2{ 1.25 3.75 } double-2 longlong-2 vconvert ."""
  46 """float-8{ 0.0 1.0 2.0 3.0 4.0 5.0 6.0 7.0 }
  47 longlong-2{ 1 3 }""" }
  48 "Packing conversions:"
  49 { $example """USING: alien.c-types math.vectors.conversion math.vectors.simd
  50 prettyprint ;
  51 SIMDS: ushort int float double ;
  52
  53 int-4{ -8 70000 6000 50 } int-4{ 4 3 2 -1 } int-4 ushort-8 vconvert .
  54 double-4{ 0.0 1.5 1.0e100 2.0 }
  55 double-4{ -1.0e100 0.0 1.0 2.0 } double-4 float-8 vconvert ."""
  56 """ushort-8{ 0 65535 6000 50 4 3 2 0 }
  57 float-8{ 0.0 1.5 1/0. 2.0 -1/0. 0.0 1.0 2.0 }""" }
  58 "Unpacking conversions:"
  59 { $example """USING: alien.c-types kernel math.vectors.conversion
  60 math.vectors.simd prettyprint ;
  61 SIMDS: uchar short ;
  62
  63 uchar-16{ 8 70 60 50 4 30 200 1 9 10 110 102 133 143 115 0 }
  64 uchar-16 short-8 vconvert [ . ] bi@"""
  65 """short-8{ 8 70 60 50 4 30 200 1 }
  66 short-8{ 9 10 110 102 133 143 115 0 }""" }
  67 } ;
  68
  69 ARTICLE: "math.vectors.conversion" "SIMD vector conversion"
  70 "The " { $vocab-link "math.vectors.conversion" } " vocabulary provides facilities for converting SIMD vectors between floating-point and integer representations and between different-sized integer representations."
  71 { $subsections
  72     vconvert
  73 } ;
  74
  75 ABOUT: "math.vectors.conversion"