libs/qvm/doc/mat_traits.html

   1 <!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'\r
   2 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>\r
   3 <html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>\r
   4 <head>\r
   5         <meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>\r
   6         <title>mat_traits</title>\r
   7         <link href='reno.css' type='text/css' rel='stylesheet'/>\r
   8 </head>\r
   9 <body>\r
  10 <div class="body-0">\r
  11 <div class="body-1">\r
  12 <div class="body-2">\r
  13 <div>\r
  14 <h1>QVM: Quaternions, Vectors, Matrices</h1>\r
  15 </div>\r
  16 <!-- Copyright (c) 2008-2016 Emil Dotchevski and Reverge Studios, Inc. -->\r
  17 <!-- Distributed under the Boost Software License, Version 1.0. (See accompanying -->\r
  18 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->\r
  19 <div class="RenoIncludeDIV"><div class="RenoAutoDIV"><h3>mat_traits</h3>\r
  20 </div>\r
  21 <div class="RenoIncludeDIV"><p><span class="RenoEscape">&#35;<!--<wiki>`&#35;</wiki>--></span>include &lt;<span class="RenoLink"><a href="boost_qvm_mat_traits_hpp.html">boost/qvm/mat_traits.hpp</a></span>&gt;</p>\r
  22 <pre>namespace boost\r
  23 {\r
  24     namespace <span class="RenoLink"><a href="qvm.html">qvm</a></span>\r
  25     {\r
  26 <span class="RenoIncludeSPAN">        template &lt;class M&gt;\r
  27         struct <span class="RenoLink">mat_traits</span>\r
  28         {\r
  29             /*main template members unspecified*/\r
  30         };\r
  31         \r
  32         /*\r
  33         User-defined (possibly partial) specializations:\r
  34         \r
  35         template &lt;&gt;\r
  36         struct <span class="RenoLink">mat_traits</span>&lt;M&gt;\r
  37         {\r
  38         <span class="RenoIncludeSPAN">    static int const <span class="RenoLink"><a href="mat_traits_Matrix_rows.html">rows</a></span> = /*user-defined*/;</span>        \r
  39         <span class="RenoIncludeSPAN">    static int const <span class="RenoLink"><a href="mat_traits_Matrix_cols.html">cols</a></span> = /*user-defined*/;</span>        \r
  40         <span class="RenoIncludeSPAN">    typedef /*user-defined*/ <span class="RenoLink"><a href="mat_traits_M_scalar_type.html">scalar_type</a></span>;</span>        \r
  41         \r
  42         <span class="RenoIncludeSPAN">    template &lt;int R,int C&gt; static inline <span class="RenoLink"><a href="mat_traits_M_scalar_type.html">scalar_type</a></span> <span class="RenoLink"><a href="mat_traits_M_read_element.html">read_element</a></span>( Matrix const &amp; m );</span>        \r
  43         <span class="RenoIncludeSPAN">    template &lt;int R,int C&gt; static inline <span class="RenoLink"><a href="mat_traits_M_scalar_type.html">scalar_type</a></span> &amp; <span class="RenoLink"><a href="mat_traits_M_write_element.html">write_element</a></span>( Matrix &amp; m );</span>        \r
  44         \r
  45         <span class="RenoIncludeSPAN">    static inline <span class="RenoLink"><a href="mat_traits_M_scalar_type.html">scalar_type</a></span> <span class="RenoLink"><a href="mat_traits_M_read_element_idx.html">read_element_idx</a></span>( int r, int c, Matrix const &amp; m );</span>        \r
  46         <span class="RenoIncludeSPAN">    static inline <span class="RenoLink"><a href="mat_traits_M_scalar_type.html">scalar_type</a></span> &amp; <span class="RenoLink"><a href="mat_traits_M_write_element_idx.html">write_element_idx</a></span>( int r, int c, Matrix &amp; m );</span>        \r
  47         };\r
  48         */</span>\r
  49     }\r
  50 }</pre>\r
  51 </div><p>The <i><span class="RenoLink">mat_traits</span></i> template must be specialized for (user-defined) matrix types in order to enable vector and matrix operations defined in Boost QVM headers for objects of those types.</p>\r
  52 <blockquote><p>Note: <i>matrix types are not required to be copyable.</i></p></blockquote>\r
  53 <p>The main <i><span class="RenoLink">mat_traits</span></i> template members are not specified. Valid specializations are required to define the following members:</p>\r
  54 <div><ul><li> <i><span class="RenoLink"><a href="mat_traits_Matrix_rows.html">rows</a></span></i>: the expression <i><span class="RenoLink">mat_traits</span>&lt;Matrix&gt;::<span class="RenoLink"><a href="mat_traits_Matrix_rows.html">rows</a></span></i> must evaluate to a compile-time integer constant greater than 0 that specifies the number of rows in a matrix.</li>\r
  55 <li> <i><span class="RenoLink"><a href="mat_traits_Matrix_cols.html">cols</a></span></i> must evaluate to a compile-time integer constant greater than 0 that specifies the number of columns in a matrix.</li>\r
  56 <li> <i><span class="RenoLink"><a href="mat_traits_M_scalar_type.html">scalar_type</a></span></i>: the expression <i><span class="RenoLink">mat_traits</span>&lt;Matrix&gt;::<span class="RenoLink"><a href="mat_traits_M_scalar_type.html">scalar_type</a></span></i> must be a value type which satisfies the <span class="RenoLink"><a href="scalar_requirements.html">scalar requirements</a></span>.</li>\r
  57 </ul></div>\r
  58 <p>In addition, valid specializations of the <i><span class="RenoLink">mat_traits</span></i> template may define the following access functions as static members, where <i>m</i> is an object of type <i>Matrix</i>, <i>R</i> and <i>C</i> are compile-time integer constants, and <i>r</i> and <i>c</i> are variables of type <i>int</i>:</p>\r
  59 <div><ul><li> <i><span class="RenoLink"><a href="mat_traits_M_read_element.html">read_element</a></span></i>: the expression <i><span class="RenoLink">mat_traits</span>&lt;Matrix&gt;::<span class="RenoLink"><a href="mat_traits_M_read_element.html">read_element</a></span>&lt;R,C&gt;(m)</i> returns either a copy of or a const reference to the element at row <i>R</i> and column <i>C</i> of <i>m</i>.</li>\r
  60 <li> <i><span class="RenoLink"><a href="mat_traits_M_write_element.html">write_element</a></span></i>: the expression <i><span class="RenoLink">mat_traits</span>&lt;Matrix&gt;::<span class="RenoLink"><a href="mat_traits_M_write_element.html">write_element</a></span>&lt;R,C&gt;(m)</i> returns mutable reference to the element at row <i>R</i> and column <i>C</i> of <i>m</i>.</li>\r
  61 <li> <i><span class="RenoLink"><a href="mat_traits_M_read_element_idx.html">read_element_idx</a></span></i>: the expression <i><span class="RenoLink">mat_traits</span>&lt;Matrix&gt;::<span class="RenoLink"><a href="mat_traits_M_read_element_idx.html">read_element_idx</a></span>(r,c,m)</i> returns either a copy of or a const reference to the element at row <i>r</i> and column <i>c</i> of <i>m</i>.</li>\r
  62 <li> <i><span class="RenoLink"><a href="mat_traits_M_write_element_idx.html">write_element_idx</a></span></i>: the expression <i><span class="RenoLink">mat_traits</span>&lt;Matrix&gt;::<span class="RenoLink"><a href="mat_traits_M_write_element_idx.html">write_element_idx</a></span>(r,c,m)</i> returns mutable reference to the element at row <i>r</i> and column <i>c</i> of <i>m</i>.</li>\r
  63 </ul></div>\r
  64 <p>It is illegal to call any of the above functions unless <i><span class="RenoLink"><a href="is_mat.html">is_mat</a></span>&lt;Matrix&gt;::value</i> is <i>true</i>. Even then, matrix types are allowed to define only a subset of the access functions. The general requirements are:</p>\r
  65 <div><ul><li> At least one of <i><span class="RenoLink"><a href="mat_traits_M_read_element.html">read_element</a></span></i> or <i><span class="RenoLink"><a href="mat_traits_M_write_element.html">write_element</a></span></i> must be defined;</li>\r
  66 <li> If <i><span class="RenoLink"><a href="mat_traits_M_read_element_idx.html">read_element_idx</a></span></i> is defined, <i><span class="RenoLink"><a href="mat_traits_M_read_element.html">read_element</a></span></i> must also be defined;</li>\r
  67 <li> If <i><span class="RenoLink"><a href="mat_traits_M_write_element_idx.html">write_element_idx</a></span></i> is defined, <i><span class="RenoLink"><a href="mat_traits_M_write_element.html">write_element</a></span></i> must also be defined.</li>\r
  68 </ul></div>\r
  69 <p>Below is an example of a user-defined 3x3 matrix type, and its corresponding specialization of the <i><span class="RenoLink">mat_traits</span></i> template:</p>\r
  70 <div class="RenoIncludeDIV"><pre>#include &lt;<span class="RenoLink"><a href="boost_qvm_mat_traits_hpp.html">boost/qvm/mat_traits.hpp</a></span>&gt;\r
  71 \r
  72 struct float33 { float a[3][3]; };\r
  73 \r
  74 namespace boost\r
  75 {\r
  76     namespace <span class="RenoLink"><a href="qvm.html">qvm</a></span>\r
  77     {\r
  78         template &lt;&gt;\r
  79         struct <span class="RenoLink">mat_traits</span>&lt;float33&gt;\r
  80         {\r
  81             static int const <span class="RenoLink"><a href="mat_traits_Matrix_rows.html">rows</a></span>=3;\r
  82             static int const <span class="RenoLink"><a href="mat_traits_Matrix_cols.html">cols</a></span>=3;\r
  83             typedef float <span class="RenoLink"><a href="mat_traits_M_scalar_type.html">scalar_type</a></span>;\r
  84 \r
  85             template &lt;int R,int C&gt; static inline <span class="RenoLink"><a href="mat_traits_M_scalar_type.html">scalar_type</a></span> &amp; <span class="RenoLink"><a href="mat_traits_M_write_element.html">write_element</a></span>( float33 &amp; m ) { return m.a[R][C]; }\r
  86             template &lt;int R,int C&gt; static inline <span class="RenoLink"><a href="mat_traits_M_scalar_type.html">scalar_type</a></span> <span class="RenoLink"><a href="mat_traits_M_read_element.html">read_element</a></span>( float33 const &amp; m ) { return m.a[R][C]; }\r
  87 \r
  88             static inline <span class="RenoLink"><a href="mat_traits_M_scalar_type.html">scalar_type</a></span> &amp; <span class="RenoLink"><a href="mat_traits_M_write_element_idx.html">write_element_idx</a></span>( int r, int c, float33 &amp; m ) { return m.a[r][c]; }\r
  89             static inline <span class="RenoLink"><a href="mat_traits_M_scalar_type.html">scalar_type</a></span> <span class="RenoLink"><a href="mat_traits_M_read_element_idx.html">read_element_idx</a></span>( int r, int c, float33 const &amp; m ) { return m.a[r][c]; }\r
  90         };\r
  91     }\r
  92 }</pre>\r
  93 <p>Equivalently, we could use the <i><span class="RenoLink"><a href="mat_traits_defaults.html">mat_traits_defaults</a></span></i> template to shorten the above to:</p>\r
  94 <pre>namespace boost\r
  95 {\r
  96     namespace <span class="RenoLink"><a href="qvm.html">qvm</a></span>\r
  97     {\r
  98         template &lt;&gt;\r
  99         struct <span class="RenoLink">mat_traits</span>&lt;float33&gt;: <span class="RenoLink"><a href="mat_traits_defaults.html">mat_traits_defaults</a></span>&lt;float33,float,3,3&gt;\r
 100         {\r
 101             template &lt;int R,int C&gt; static inline <span class="RenoLink"><a href="mat_traits_M_scalar_type.html">scalar_type</a></span> &amp; <span class="RenoLink"><a href="mat_traits_M_write_element.html">write_element</a></span>( float33 &amp; m ) { return m.a[R][C]; }\r
 102 \r
 103             static inline <span class="RenoLink"><a href="mat_traits_M_scalar_type.html">scalar_type</a></span> &amp; <span class="RenoLink"><a href="mat_traits_M_write_element_idx.html">write_element_idx</a></span>( int r, int c, float33 &amp; m ) { return m.a[r][c]; }\r
 104         };\r
 105     }\r
 106 }</pre>\r
 107 </div></div><div class="RenoAutoDIV"><div class="RenoHR"><hr/></div>\r
 108 See also: <span class="RenoPageList"><a href="assign_mat_mat_.html">assign(mat,mat)</a>&nbsp;| <a href="boost_qvm_mat_traits_hpp.html">boost/qvm/mat_traits.hpp</a>&nbsp;| <a href="boost_qvm_mat_traits_array_hpp.html">boost/qvm/mat_traits_array.hpp</a>&nbsp;| <a href="boost_qvm_mat_traits_defaults_hpp.html">boost/qvm/mat_traits_defaults.hpp</a>&nbsp;| <a href="cmp_mat_mat_.html">cmp(mat,mat)</a>&nbsp;| <a href="convert_to_mat_.html">convert_to(mat)</a>&nbsp;| <a href="convert_to_quat_.html">convert_to(quat)</a>&nbsp;| <a href="deduce_mat.html">deduce_mat</a>&nbsp;| <a href="deduce_mat2.html">deduce_mat2</a>&nbsp;| <a href="determinant.html">determinant</a>&nbsp;| <a href="inverse_mat_.html">inverse(mat)</a>&nbsp;| <a href="is_mat.html">is_mat</a>&nbsp;| <a href="mat.html">mat</a>&nbsp;| <a href="mat_traits_M_read_element.html">mat_traits&lt;M&gt;::read_element</a>&nbsp;| <a href="mat_traits_M_read_element_idx.html">mat_traits&lt;M&gt;::read_element_idx</a>&nbsp;| <a href="mat_traits_M_scalar_type.html">mat_traits&lt;M&gt;::scalar_type</a>&nbsp;| <a href="mat_traits_M_write_element.html">mat_traits&lt;M&gt;::write_element</a>&nbsp;| <a href="mat_traits_M_write_element_idx.html">mat_traits&lt;M&gt;::write_element_idx</a>&nbsp;| <a href="mat_traits_Matrix_cols.html">mat_traits&lt;Matrix&gt;::cols</a>&nbsp;| <a href="mat_traits_Matrix_rows.html">mat_traits&lt;Matrix&gt;::rows</a>&nbsp;| <a href="mat_traits_defaults.html">mat_traits_defaults</a>&nbsp;| <a href="operator_not_eq_mat_mat_.html">operator!=(mat,mat)</a>&nbsp;| <a href="operator_times_mat_mat_.html">operator*(mat,mat)</a>&nbsp;| <a href="operator_times_mat_vec_.html">operator*(mat,vec)</a>&nbsp;| <a href="operator_times_vec_mat_.html">operator*(vec,mat)</a>&nbsp;| <a href="operator_mul_eq_mat_mat_.html">operator*=(mat,mat)</a>&nbsp;| <a href="operator_plus_mat_mat_.html">operator+(mat,mat)</a>&nbsp;| <a href="operator_add_mat_mat_.html">operator+=(mat,mat)</a>&nbsp;| <a href="operator_minus_mat_mat_.html">operator-(mat,mat)</a>&nbsp;| <a href="operator_sub_eq_mat_mat_.html">operator-=(mat,mat)</a>&nbsp;| <a href="operator_eq_mat_mat_.html">operator==(mat,mat)</a>&nbsp;| <a href="rotate_mat_vec_scalar_.html">rotate(mat,vec,scalar)</a>&nbsp;| <a href="rotate_x_mat_scalar_.html">rotate_x(mat,scalar)</a>&nbsp;| <a href="rotate_y_mat_scalar_.html">rotate_y(mat,scalar)</a>&nbsp;| <a href="rotate_z_mat_scalar_.html">rotate_z(mat,scalar)</a>&nbsp;| <a href="SFINAE_enable_if.html">SFINAE/enable_if</a>&nbsp;| <a href="scalar.html">scalar</a>&nbsp;| <a href="set_identity_mat_.html">set_identity(mat)</a>&nbsp;| <a href="set_rot_mat_vec_scalar_.html">set_rot(mat,vec,scalar)</a>&nbsp;| <a href="set_rotx_mat_scalar_.html">set_rotx(mat,scalar)</a>&nbsp;| <a href="set_roty_mat_scalar_.html">set_roty(mat,scalar)</a>&nbsp;| <a href="set_rotz_mat_scalar_.html">set_rotz(mat,scalar)</a>&nbsp;| <a href="set_zero_mat_.html">set_zero(mat)</a>&nbsp;| <a href="transform_point.html">transform_point</a>&nbsp;| <a href="transform_vector.html">transform_vector</a>&nbsp;| <a href="translation.html">translation</a>&nbsp;| <a href="view_proxy.html">View Proxy</a></span>\r
 109 </div>\r
 110 <!-- Copyright (c) 2008-2016 Emil Dotchevski and Reverge Studios, Inc. -->\r
 111 <!-- Distributed under the Boost Software License, Version 1.0. (See accompanying -->\r
 112 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->\r
 113 <div id="footer">\r
 114 <p>\r
 115 <a class="logo" href="http://jigsaw.w3.org/css-validator/check/referer"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>\r
 116 <a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>\r
 117 <small>Copyright (c) 2008-2016 by Emil Dotchevski and Reverge Studios, Inc.<br/>\r
 118 Distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Version 1.0</a>.</small>\r
 119 </p>\r
 120 </div>\r
 121 </div>\r
 122 </div>\r
 123 </div>\r
 124 </body>\r
 125 </html>\r