From fca550d567943190b43788b59be2c0281733d3fa Mon Sep 17 00:00:00 2001 From: Joe Groff Date: Sun, 18 Oct 2009 21:25:09 -0500 Subject: [PATCH] math.vectors.conversion docs --- .../vectors/conversion/conversion-docs.factor | 75 +++++++++++++++++++ basis/math/vectors/vectors-docs.factor | 15 ++-- 2 files changed, 84 insertions(+), 6 deletions(-) create mode 100644 basis/math/vectors/conversion/conversion-docs.factor diff --git a/basis/math/vectors/conversion/conversion-docs.factor b/basis/math/vectors/conversion/conversion-docs.factor new file mode 100644 index 0000000000..9fe5ac4c17 --- /dev/null +++ b/basis/math/vectors/conversion/conversion-docs.factor @@ -0,0 +1,75 @@ +! (c)2009 Joe Groff bsd license +USING: classes help.markup help.syntax kernel quotations ; +IN: math.vectors.conversion + +HELP: bad-vconvert +{ $values + { "from-type" "a SIMD type" } { "to-type" "a SIMD type" } +} +{ $description "This error is thrown when " { $link vconvert } " is given two SIMD types it cannot directly convert." } ; + +HELP: bad-vconvert-input +{ $values + { "value" object } { "expected-type" class } +} +{ $description "This error is thrown when an input to " { $link vconvert } " does not match the expected " { $snippet "from-type" } "." } ; + +{ bad-vconvert bad-vconvert-input } related-words + +HELP: vconvert +{ $values + { "from-type" "a SIMD type" } { "to-type" "a SIMD type" } +} +{ $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:" +{ $list +{ "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" } "." } +{ "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" } "." } +{ "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" } "." } +{ "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" } "." } +} +{ $snippet "from-type" } " and " { $snippet "to-type" } " must adhere to the following restrictions; a " { $link bad-vconvert } " error will be thrown otherwise:" +{ $list +{ { $snippet "from-type" } " and " { $snippet "to-type" } " must have the same byte length. You cannot currently convert between 128- and 256-bit vector types." } +{ "For conversions between floating-point and integer vectors, " { $snippet "from-type" } " and " { $snippet "to-type" } " must have the same element length." } +{ "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." } +{ "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." } +} +} +{ $examples +"Conversion between integer and float vectors:" +{ $example """USING: alien.c-types math.vectors.conversion math.vectors.simd +prettyprint ; +SIMDS: int float longlong double ; + +int-8{ 0 1 2 3 4 5 6 7 } int-8 float-8 vconvert . +double-2{ 1.25 3.75 } double-2 longlong-2 vconvert .""" +"""float-8{ 0.0 1.0 2.0 3.0 4.0 5.0 6.0 7.0 } +longlong-2{ 1 3 }""" } +"Packing conversions:" +{ $example """USING: alien.c-types math.vectors.conversion math.vectors.simd +prettyprint ; +SIMDS: ushort int float double ; + +int-4{ -8 70000 6000 50 } int-4{ 4 3 2 -1 } int-4 ushort-8 vconvert . +double-4{ 0.0 1.5 1.0e100 2.0 } +double-4{ -1.0e100 0.0 1.0 2.0 } double-4 float-8 vconvert .""" +"""ushort-8{ 0 65535 6000 50 4 3 2 0 } +float-8{ 0.0 1.5 1/0. 2.0 -1/0. 0.0 1.0 2.0 }""" } +"Unpacking conversions:" +{ $example """USING: alien.c-types kernel math.vectors.conversion +math.vectors.simd prettyprint ; +SIMDS: uchar short ; + +uchar-16{ 8 70 60 50 4 30 200 1 9 10 110 102 133 143 115 0 } +uchar-16 short-8 vconvert [ . ] bi@""" +"""short-8{ 8 70 60 50 4 30 200 1 } +short-8{ 9 10 110 102 133 143 115 0 }""" } +} ; + +ARTICLE: "math.vectors.conversion" "SIMD vector conversion" +"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." +{ $subsections + vconvert +} ; + +ABOUT: "math.vectors.conversion" diff --git a/basis/math/vectors/vectors-docs.factor b/basis/math/vectors/vectors-docs.factor index 27940f9f6c..71e86417f5 100644 --- a/basis/math/vectors/vectors-docs.factor +++ b/basis/math/vectors/vectors-docs.factor @@ -55,12 +55,15 @@ ARTICLE: "math-vectors-shuffle" "Vector shuffling, packing, and unpacking" "These operations are primarily meant to be used with " { $vocab-link "math.vectors.simd" } " types. The software fallbacks for types not supported by hardware will not perform well." } $nl -{ $subsection vshuffle } -{ $subsection vbroadcast } -{ $subsection hlshift } -{ $subsection hrshift } -{ $subsection vmerge } -{ $subsection (vmerge) } ; +{ $subsections + vshuffle + vbroadcast + hlshift + hrshift + vmerge + (vmerge) +} +"See the " { $vocab-link "math.vectors.conversion" } " vocabulary for packing, unpacking, and converting vectors." ; ARTICLE: "math-vectors-logic" "Vector component- and bit-wise logic" { $notes