Milena (Olena)  User documentation 2.0a Id
 All Classes Namespaces Functions Variables Typedefs Enumerator Groups Pages
2008__tour1_extra.cc
1 // Copyright (C) 2007 EPITA Research and Development Laboratory
2 //
3 // This file is part of Olena.
4 //
5 // Olena is free software: you can redistribute it and/or modify it under
6 // the terms of the GNU General Public License as published by the Free
7 // Software Foundation, version 2 of the License.
8 //
9 // Olena is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 // General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Olena. If not, see <http://www.gnu.org/licenses/>.
16 //
17 // As a special exception, you may use this file as part of a free
18 // software project without restriction. Specifically, if other files
19 // instantiate templates or use macros or inline functions from this
20 // file, or you compile this file and link it with other files to produce
21 // an executable, this file does not by itself cause the resulting
22 // executable to be covered by the GNU General Public License. This
23 // exception does not however invalidate any other reasons why the
24 // executable file might be covered by the GNU General Public License.
25 
26 // File: tour1_extra.cc.
27 
28 #include <oln/core/1d/image1d.hh>
29 #include <oln/arith/plus.hh>
30 #include <oln/debug/println.hh>
31 
32 
33 
34 int main()
35 {
36  using namespace oln;
37 
38 
39  // Let us take a few examples to illustrate how images and data are
40  // managed. In these examples, we will use the notion of "block of
41  // instructions" from the C/C++ languages: "{" ... "}".
42 
43 
44 
45 
46  // Example 1:
47 
48  { // A new block starts here.
49 
50  image1d<float> local_ima(1000);
51  // A non-empty image is created; a memory buffer is automatically
52  // allocated to store image data. Some code using 'local_ima' can
53  // be inserted here...
54 
55  } // The block ends and 'local_ima' is not more accessible.
56 
57  // At the end of the block, since the user cannot use 'local_ima'
58  // anymore, the memory is automatically deallocated.
59 
60 
61 
62 
63  // Example 2:
64 
65  image1d<float> ima; // An empty image---a variable.
66 
67  { // A new block.
68 
69  image1d<float> local_ima(1000); // A non-empty image.
70  // Some work is performed with 'local_ima' here.
71  // ...
72  ima = local_ima; // Last, we state that ima IS local_ima.
73 
74  } // End of the block: 'local_ima' is no more accessible.
75 
76  assert(not ima.is_empty()); // We test that 'ima' is no more empty.
77 
78  // Since we state that "ima IS local_ima" and since 'ima' is still
79  // accessible by the user, the contents of 'local_ima' is preserved.
80 
81  // Conversely to the example 1, the memory allocated for 'local_ima'
82  // is thus NOT deallocated: the data of 'local_ima' is "transfered"
83  // to 'ima'. There is NO data "copy" involved during this transfer
84  // so it is fast and it saves memory.
85 
86 
87 
88 
89  // Example 3:
90 
91  {
92  image1d<int> orig(5); // An original image.
93  for (int i = 0; i < 5; ++i)
94  orig.at(i) = i;
95  debug::println(orig);
96  // 0 1 2 3 4
97 
98  image1d<int> ima = orig; // 'ima' is 'orig'.
99  ima = ima + ima; // Point-wise sum of ima and itself.
100  debug::println(ima);
101  // 0 2 4 6 8
102 
103  debug::println(orig);
104  // 0 1 2 3 4
105  }
106 
107  // To explain this result, let us detail the point-wise sum line.
108  // The assignment "ima = ima + ima" is a two-step process: first
109  // "ima + ima" is computed, then the assignment is performed. This
110  // line can be rewritten as:
111 
112  // image1d<int> anon = ima + ima; // line (a)
113  // ima = anon; // line (b)
114 
115  // where 'anon' is the "anonymous" result of the sum. We can see
116  // that 'ima' is used in line (a) to compute a new image, namely
117  // 'anon'. At that precise line, 'ima' still designates 'orig'. At
118  // line (b) the definition of 'ima' changes: 'ima' was designating
119  // 'orig', now it designates 'anon', that is, the sum result.
120  // Eventually the data of 'orig' have never changed since it has
121  // been initialized.
122 
123  // In this example, two images with effective data have been
124  // created: the sum result, which is accessible through 'ima', and
125  // 'orig'.
126 
127  // The same explanation in pictures. When the sum "ima + ima" is
128  // computed, the images and their data look like:
129  //
130  // +-----------+
131  // orig --> | 0 1 2 3 4 |
132  // +-----------+
133  // ^
134  // ima ______|
135  //
136  // +-----------+
137  // anon --> | 0 2 4 6 8 |
138  // +-----------+
139  //
140  // Then the assignment modifies this scheme into:
141  //
142  // +-----------+
143  // orig --> | 0 1 2 3 4 |
144  // +-----------+
145  // ima ______
146  // |
147  // v
148  // +-----------+
149  // anon --> | 0 2 4 6 8 |
150  // +-----------+
151  //
152  // and the temporary 'anon' disappears.
153 
154 
155 
156 
157 
158  // Example 4:
159 
160  {
161  image1d<int> ima(5);
162  for (int i = 0; i < 5; ++i)
163  ima.at(i) = i;
164  debug::println(ima);
165  // 0 1 2 3 4
166 
167  ima = ima + ima;
168  debug::println(ima);
169  // 0 2 4 6 8
170  }
171 
172  // Let us re-write the assignment line:
173 
174  // image1d<int> anon = ima + ima; // line (a)
175  // ima = anon; // line (b)
176 
177  // A new image, 'anon', is created to store the sum result; this
178  // image is just like a temporary object since it is anonymous. In
179  // line (a) the definition of 'ima' changes: it was the original
180  // image with its data being "0 1 2 3 4" and it now designates the
181  // sum result. The original data becomes inaccessible by the user
182  // so it is automatically deallocated.
183 
184  // The same explanation In pictures. After the sum is computed, we
185  // have:
186  // +-----------+
187  // ima ---> | 0 1 2 3 4 |
188  // +-----------+
189  //
190  // +-----------+
191  // anon --> | 0 2 4 6 8 |
192  // +-----------+
193  //
194  // and the assignment of 'ima' leads to:
195  //
196  // +-----------+
197  // ima | 0 1 2 3 4 |
198  // | +-----------+
199  // |_________
200  // |
201  // v
202  // +-----------+
203  // anon --> | 0 2 4 6 8 |
204  // +-----------+
205  //
206  // so the original data, unreachable, are deallocated and the
207  // temporary 'anon' disappears; we end up with:
208  //
209  // +-----------+
210  // ima ---> | 0 2 4 6 8 |
211  // +-----------+
212 }