Fix multi layer/multi pass render
[blender.git] / source / blender / blenkernel / intern / blendfile.c
1 /*
2  * ***** BEGIN GPL LICENSE BLOCK *****
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License
6  * as published by the Free Software Foundation; either version 2
7  * of the License, or (at your option) any later version.
8  *
9  * This program 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
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software Foundation,
16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
17  *
18  * ***** END GPL LICENSE BLOCK *****
19  */
20
21 /** \file blender/blenkernel/intern/blendfile.c
22  *  \ingroup bke
23  *
24  * High level `.blend` file read/write,
25  * and functions for writing *partial* files (only selected data-blocks).
26  */
27
28 #include <stdlib.h>
29 #include <string.h>
30
31 #include "MEM_guardedalloc.h"
32
33 #include "DNA_scene_types.h"
34 #include "DNA_screen_types.h"
35 #include "DNA_workspace_types.h"
36
37 #include "BLI_listbase.h"
38 #include "BLI_string.h"
39 #include "BLI_path_util.h"
40 #include "BLI_utildefines.h"
41
42 #include "IMB_colormanagement.h"
43
44 #include "BKE_appdir.h"
45 #include "BKE_blender.h"
46 #include "BKE_blender_version.h"
47 #include "BKE_blendfile.h"
48 #include "BKE_bpath.h"
49 #include "BKE_context.h"
50 #include "BKE_global.h"
51 #include "BKE_ipo.h"
52 #include "BKE_layer.h"
53 #include "BKE_library.h"
54 #include "BKE_main.h"
55 #include "BKE_report.h"
56 #include "BKE_scene.h"
57 #include "BKE_screen.h"
58 #include "BKE_workspace.h"
59
60 #include "BLO_readfile.h"
61 #include "BLO_writefile.h"
62
63 #include "RNA_access.h"
64
65 #include "RE_pipeline.h"
66
67 #ifdef WITH_PYTHON
68 #  include "BPY_extern.h"
69 #endif
70
71 /* -------------------------------------------------------------------- */
72
73 /** \name High Level `.blend` file read/write.
74  * \{ */
75
76 static bool clean_paths_visit_cb(void *UNUSED(userdata), char *path_dst, const char *path_src)
77 {
78         strcpy(path_dst, path_src);
79         BLI_path_native_slash(path_dst);
80         return !STREQ(path_dst, path_src);
81 }
82
83 /* make sure path names are correct for OS */
84 static void clean_paths(Main *main)
85 {
86         Scene *scene;
87
88         BKE_bpath_traverse_main(main, clean_paths_visit_cb, BKE_BPATH_TRAVERSE_SKIP_MULTIFILE, NULL);
89
90         for (scene = main->scene.first; scene; scene = scene->id.next) {
91                 BLI_path_native_slash(scene->r.pic);
92         }
93 }
94
95 static bool wm_scene_is_visible(wmWindowManager *wm, Scene *scene)
96 {
97         wmWindow *win;
98         for (win = wm->windows.first; win; win = win->next) {
99                 if (win->scene == scene) {
100                         return true;
101                 }
102         }
103         return false;
104 }
105
106 /**
107  * Context matching, handle no-ui case
108  *
109  * \note this is called on Undo so any slow conversion functions here
110  * should be avoided or check (mode != LOAD_UNDO).
111  *
112  * \param bfd: Blend file data, freed by this function on exit.
113  * \param filepath: File path or identifier.
114  */
115 static void setup_app_data(
116         bContext *C, BlendFileData *bfd,
117         const char *filepath, ReportList *reports)
118 {
119         Scene *curscene = NULL;
120         const bool is_startup = (bfd->filename[0] == '\0');
121         const bool recover = (G.fileflags & G_FILE_RECOVER) != 0;
122         enum {
123                 LOAD_UI = 1,
124                 LOAD_UI_OFF,
125                 LOAD_UNDO,
126         } mode;
127
128         /* may happen with library files - UNDO file should never have NULL cursccene... */
129         if (ELEM(NULL, bfd->curscreen, bfd->curscene)) {
130                 BKE_report(reports, RPT_WARNING, "Library file, loading empty scene");
131                 mode = LOAD_UI_OFF;
132         }
133         else if (BLI_listbase_is_empty(&bfd->main->screen)) {
134                 mode = LOAD_UNDO;
135         }
136         else if ((G.fileflags & G_FILE_NO_UI) && (is_startup == false)) {
137                 mode = LOAD_UI_OFF;
138         }
139         else {
140                 mode = LOAD_UI;
141         }
142
143         /* Free all render results, without this stale data gets displayed after loading files */
144         if (mode != LOAD_UNDO) {
145                 RE_FreeAllRenderResults();
146         }
147
148         /* Only make filepaths compatible when loading for real (not undo) */
149         if (mode != LOAD_UNDO) {
150                 clean_paths(bfd->main);
151         }
152
153         /* XXX here the complex windowmanager matching */
154
155         /* no load screens? */
156         if (mode != LOAD_UI) {
157                 /* Logic for 'track_undo_scene' is to keep using the scene which the active screen has,
158                  * as long as the scene associated with the undo operation is visible in one of the open windows.
159                  *
160                  * - 'curscreen->scene' - scene the user is currently looking at.
161                  * - 'bfd->curscene' - scene undo-step was created in.
162                  *
163                  * This means users can have 2+ windows open and undo in both without screens switching.
164                  * But if they close one of the screens,
165                  * undo will ensure that the scene being operated on will be activated
166                  * (otherwise we'd be undoing on an off-screen scene which isn't acceptable).
167                  * see: T43424
168                  */
169                 wmWindow *win;
170                 bScreen *curscreen = NULL;
171                 SceneLayer *cur_render_layer;
172                 bool track_undo_scene;
173
174                 /* comes from readfile.c */
175                 SWAP(ListBase, G.main->wm, bfd->main->wm);
176                 SWAP(ListBase, G.main->workspaces, bfd->main->workspaces);
177                 SWAP(ListBase, G.main->screen, bfd->main->screen);
178
179                 /* we re-use current window and screen */
180                 win = CTX_wm_window(C);
181                 curscreen = CTX_wm_screen(C);
182                 /* but use Scene pointer from new file */
183                 curscene = bfd->curscene;
184                 cur_render_layer = bfd->cur_render_layer;
185
186                 track_undo_scene = (mode == LOAD_UNDO && curscreen && curscene && bfd->main->wm.first);
187
188                 if (curscene == NULL) {
189                         curscene = bfd->main->scene.first;
190                 }
191                 /* empty file, we add a scene to make Blender work */
192                 if (curscene == NULL) {
193                         curscene = BKE_scene_add(bfd->main, "Empty");
194                 }
195                 if (cur_render_layer == NULL) {
196                         /* fallback to scene layer */
197                         cur_render_layer = BKE_scene_layer_from_scene_get(curscene);
198                 }
199
200                 if (track_undo_scene) {
201                         /* keep the old (free'd) scene, let 'blo_lib_link_screen_restore'
202                          * replace it with 'curscene' if its needed */
203                 }
204                 /* and we enforce curscene to be in current screen */
205                 else if (win) { /* can run in bgmode */
206                         win->scene = curscene;
207                 }
208
209                 /* BKE_blender_globals_clear will free G.main, here we can still restore pointers */
210                 blo_lib_link_restore(bfd->main, CTX_wm_manager(C), curscene, cur_render_layer);
211                 if (win) {
212                         curscene = win->scene;
213                 }
214
215                 if (track_undo_scene) {
216                         wmWindowManager *wm = bfd->main->wm.first;
217                         if (wm_scene_is_visible(wm, bfd->curscene) == false) {
218                                 curscene = bfd->curscene;
219                                 win->scene = curscene;
220                                 BKE_screen_view3d_scene_sync(curscreen, curscene);
221                         }
222                 }
223
224                 /* We need to tag this here because events may be handled immediately after.
225                  * only the current screen is important because we wont have to handle
226                  * events from multiple screens at once.*/
227                 {
228                         BKE_screen_manipulator_tag_refresh(curscreen);
229                 }
230         }
231
232         /* free G.main Main database */
233 //      CTX_wm_manager_set(C, NULL);
234         BKE_blender_globals_clear();
235
236         /* clear old property update cache, in case some old references are left dangling */
237         RNA_property_update_cache_free();
238
239         G.main = bfd->main;
240
241         CTX_data_main_set(C, G.main);
242
243         if (bfd->user) {
244
245                 /* only here free userdef themes... */
246                 BKE_blender_userdef_free_data(&U);
247
248                 U = *bfd->user;
249
250                 /* Security issue: any blend file could include a USER block.
251                  *
252                  * Currently we load prefs from BLENDER_STARTUP_FILE and later on load BLENDER_USERPREF_FILE,
253                  * to load the preferences defined in the users home dir.
254                  *
255                  * This means we will never accidentally (or maliciously)
256                  * enable scripts auto-execution by loading a '.blend' file.
257                  */
258                 U.flag |= USER_SCRIPT_AUTOEXEC_DISABLE;
259
260                 MEM_freeN(bfd->user);
261         }
262
263         /* case G_FILE_NO_UI or no screens in file */
264         if (mode != LOAD_UI) {
265                 /* leave entire context further unaltered? */
266                 CTX_data_scene_set(C, curscene);
267         }
268         else {
269                 /* Keep state from preferences. */
270                 const int fileflags_skip = G_FILE_FLAGS_RUNTIME;
271                 G.fileflags = (G.fileflags & fileflags_skip) | (bfd->fileflags & ~fileflags_skip);
272                 CTX_wm_manager_set(C, G.main->wm.first);
273                 CTX_wm_screen_set(C, bfd->curscreen);
274                 CTX_data_scene_set(C, bfd->curscene);
275                 CTX_wm_area_set(C, NULL);
276                 CTX_wm_region_set(C, NULL);
277                 CTX_wm_menu_set(C, NULL);
278                 curscene = bfd->curscene;
279         }
280
281         /* this can happen when active scene was lib-linked, and doesn't exist anymore */
282         if (CTX_data_scene(C) == NULL) {
283                 wmWindow *win = CTX_wm_window(C);
284
285                 /* in case we don't even have a local scene, add one */
286                 if (!G.main->scene.first)
287                         BKE_scene_add(G.main, "Empty");
288
289                 CTX_data_scene_set(C, G.main->scene.first);
290                 win->scene = CTX_data_scene(C);
291                 curscene = CTX_data_scene(C);
292         }
293
294         BLI_assert(curscene == CTX_data_scene(C));
295
296
297         /* special cases, override loaded flags: */
298         if (G.f != bfd->globalf) {
299                 const int flags_keep = (G_SWAP_EXCHANGE | G_SCRIPT_AUTOEXEC | G_SCRIPT_OVERRIDE_PREF);
300                 bfd->globalf = (bfd->globalf & ~flags_keep) | (G.f & flags_keep);
301         }
302
303
304         G.f = bfd->globalf;
305
306 #ifdef WITH_PYTHON
307         /* let python know about new main */
308         BPY_context_update(C);
309 #endif
310
311         /* FIXME: this version patching should really be part of the file-reading code,
312          * but we still get too many unrelated data-corruption crashes otherwise... */
313         if (G.main->versionfile < 250)
314                 do_versions_ipos_to_animato(G.main);
315
316         G.main->recovered = 0;
317
318         /* startup.blend or recovered startup */
319         if (bfd->filename[0] == 0) {
320                 G.main->name[0] = 0;
321         }
322         else if (recover && G.relbase_valid) {
323                 /* in case of autosave or quit.blend, use original filename instead
324                  * use relbase_valid to make sure the file is saved, else we get <memory2> in the filename */
325                 filepath = bfd->filename;
326                 G.main->recovered = 1;
327
328                 /* these are the same at times, should never copy to the same location */
329                 if (G.main->name != filepath)
330                         BLI_strncpy(G.main->name, filepath, FILE_MAX);
331         }
332
333         /* baseflags, groups, make depsgraph, etc */
334         /* first handle case if other windows have different scenes visible */
335         if (mode == LOAD_UI) {
336                 wmWindowManager *wm = G.main->wm.first;
337
338                 if (wm) {
339                         for (wmWindow *win = wm->windows.first; win; win = win->next) {
340                                 if (win->scene && win->scene != curscene) {
341                                         BKE_scene_set_background(G.main, win->scene);
342                                 }
343                         }
344                 }
345         }
346
347         /* Setting scene might require having a dependency graph, with copy on write
348          * we need to make sure we ensure scene has correct color management before
349          * constructing dependency graph.
350          */
351         if (mode != LOAD_UNDO) {
352                 IMB_colormanagement_check_file_config(G.main);
353         }
354
355         BKE_scene_set_background(G.main, curscene);
356
357         if (mode != LOAD_UNDO) {
358                 /* TODO(sergey): Can this be also move above? */
359                 RE_FreeAllPersistentData();
360         }
361
362         MEM_freeN(bfd);
363
364 }
365
366 static int handle_subversion_warning(Main *main, ReportList *reports)
367 {
368         if (main->minversionfile > BLENDER_VERSION ||
369             (main->minversionfile == BLENDER_VERSION &&
370              main->minsubversionfile > BLENDER_SUBVERSION))
371         {
372                 BKE_reportf(reports, RPT_ERROR, "File written by newer Blender binary (%d.%d), expect loss of data!",
373                             main->minversionfile, main->minsubversionfile);
374         }
375
376         return 1;
377 }
378
379 int BKE_blendfile_read(
380         bContext *C, const char *filepath,
381         ReportList *reports, int skip_flags)
382 {
383         BlendFileData *bfd;
384         int retval = BKE_BLENDFILE_READ_OK;
385
386         /* don't print user-pref loading */
387         if (strstr(filepath, BLENDER_STARTUP_FILE) == NULL) {
388                 printf("Read blend: %s\n", filepath);
389         }
390
391         bfd = BLO_read_from_file(filepath, reports, skip_flags);
392         if (bfd) {
393                 if (bfd->user) {
394                         retval = BKE_BLENDFILE_READ_OK_USERPREFS;
395                 }
396
397                 if (0 == handle_subversion_warning(bfd->main, reports)) {
398                         BKE_main_free(bfd->main);
399                         MEM_freeN(bfd);
400                         bfd = NULL;
401                         retval = BKE_BLENDFILE_READ_FAIL;
402                 }
403                 else {
404                         setup_app_data(C, bfd, filepath, reports);
405                 }
406         }
407         else
408                 BKE_reports_prependf(reports, "Loading '%s' failed: ", filepath);
409
410         return (bfd ? retval : BKE_BLENDFILE_READ_FAIL);
411 }
412
413 bool BKE_blendfile_read_from_memory(
414         bContext *C, const void *filebuf, int filelength,
415         ReportList *reports, int skip_flags, bool update_defaults)
416 {
417         BlendFileData *bfd;
418
419         bfd = BLO_read_from_memory(filebuf, filelength, reports, skip_flags);
420         if (bfd) {
421                 if (update_defaults)
422                         BLO_update_defaults_startup_blend(bfd->main);
423                 setup_app_data(C, bfd, "<memory2>", reports);
424         }
425         else {
426                 BKE_reports_prepend(reports, "Loading failed: ");
427         }
428
429         return (bfd != NULL);
430 }
431
432 /* memfile is the undo buffer */
433 bool BKE_blendfile_read_from_memfile(
434         bContext *C, struct MemFile *memfile,
435         ReportList *reports, int skip_flags)
436 {
437         BlendFileData *bfd;
438
439         bfd = BLO_read_from_memfile(CTX_data_main(C), G.main->name, memfile, reports, skip_flags);
440         if (bfd) {
441                 /* remove the unused screens and wm */
442                 while (bfd->main->wm.first)
443                         BKE_libblock_free(bfd->main, bfd->main->wm.first);
444                 while (bfd->main->screen.first)
445                         BKE_libblock_free(bfd->main, bfd->main->screen.first);
446
447                 setup_app_data(C, bfd, "<memory1>", reports);
448         }
449         else {
450                 BKE_reports_prepend(reports, "Loading failed: ");
451         }
452
453         return (bfd != NULL);
454 }
455
456 /**
457  * Utility to make a file 'empty' used for startup to optionally give an empty file.
458  * Handy for tests.
459  */
460 void BKE_blendfile_read_make_empty(bContext *C)
461 {
462         Main *bmain = CTX_data_main(C);
463
464         ListBase *lbarray[MAX_LIBARRAY];
465         ID *id;
466         int a;
467
468         a = set_listbasepointers(bmain, lbarray);
469         while (a--) {
470                 id = lbarray[a]->first;
471                 if (id != NULL) {
472                         if (ELEM(GS(id->name), ID_SCE, ID_SCR, ID_WM)) {
473                                 continue;
474                         }
475                         while ((id = lbarray[a]->first)) {
476                                 BKE_libblock_delete(bmain, id);
477                         }
478                 }
479         }
480 }
481
482 /* only read the userdef from a .blend */
483 UserDef *BKE_blendfile_userdef_read(const char *filepath, ReportList *reports)
484 {
485         BlendFileData *bfd;
486         UserDef *userdef = NULL;
487
488         bfd = BLO_read_from_file(filepath, reports, BLO_READ_SKIP_ALL & ~BLO_READ_SKIP_USERDEF);
489         if (bfd) {
490                 if (bfd->user) {
491                         userdef = bfd->user;
492                 }
493                 BKE_main_free(bfd->main);
494                 MEM_freeN(bfd);
495         }
496
497         return userdef;
498 }
499
500
501 UserDef *BKE_blendfile_userdef_read_from_memory(
502         const void *filebuf, int filelength,
503         ReportList *reports)
504 {
505         BlendFileData *bfd;
506         UserDef *userdef = NULL;
507
508         bfd = BLO_read_from_memory(filebuf, filelength, reports, BLO_READ_SKIP_ALL & ~BLO_READ_SKIP_USERDEF);
509         if (bfd) {
510                 if (bfd->user) {
511                         userdef = bfd->user;
512                 }
513                 BKE_main_free(bfd->main);
514                 MEM_freeN(bfd);
515         }
516         else {
517                 BKE_reports_prepend(reports, "Loading failed: ");
518         }
519
520         return userdef;
521 }
522
523
524 /**
525  * Only write the userdef in a .blend
526  * \return success
527  */
528 bool BKE_blendfile_userdef_write(const char *filepath, ReportList *reports)
529 {
530         Main *mainb = MEM_callocN(sizeof(Main), "empty main");
531         bool ok = false;
532
533         if (BLO_write_file(mainb, filepath, G_FILE_USERPREFS, reports, NULL)) {
534                 ok = true;
535         }
536
537         MEM_freeN(mainb);
538
539         return ok;
540 }
541
542 WorkspaceConfigFileData *BKE_blendfile_workspace_config_read(const char *filepath, ReportList *reports)
543 {
544         BlendFileData *bfd;
545         WorkspaceConfigFileData *workspace_config = NULL;
546
547         bfd = BLO_read_from_file(filepath, reports, BLO_READ_SKIP_USERDEF);
548         if (bfd) {
549                 workspace_config = MEM_mallocN(sizeof(*workspace_config), __func__);
550                 workspace_config->main = bfd->main;
551                 workspace_config->workspaces = bfd->main->workspaces;
552
553                 MEM_freeN(bfd);
554         }
555
556         return workspace_config;
557 }
558
559 bool BKE_blendfile_workspace_config_write(Main *bmain, const char *filepath, ReportList *reports)
560 {
561         int fileflags = G.fileflags & ~(G_FILE_NO_UI | G_FILE_AUTOPLAY | G_FILE_HISTORY);
562         bool retval = false;
563
564         BKE_blendfile_write_partial_begin(bmain);
565
566         for (WorkSpace *workspace = bmain->workspaces.first; workspace; workspace = workspace->id.next) {
567                 BKE_blendfile_write_partial_tag_ID(&workspace->id, true);
568         }
569
570         if (BKE_blendfile_write_partial(bmain, filepath, fileflags, reports)) {
571                 retval = true;
572         }
573
574         BKE_blendfile_write_partial_end(bmain);
575
576         return retval;
577 }
578
579 void BKE_blendfile_workspace_config_data_free(WorkspaceConfigFileData *workspace_config)
580 {
581         BKE_main_free(workspace_config->main);
582         MEM_freeN(workspace_config);
583 }
584
585 /** \} */
586
587
588 /* -------------------------------------------------------------------- */
589
590 /** \name Partial `.blend` file save.
591  * \{ */
592
593 void BKE_blendfile_write_partial_begin(Main *bmain_src)
594 {
595         BKE_main_id_tag_all(bmain_src, LIB_TAG_NEED_EXPAND | LIB_TAG_DOIT, false);
596 }
597
598 void BKE_blendfile_write_partial_tag_ID(ID *id, bool set)
599 {
600         if (set) {
601                 id->tag |= LIB_TAG_NEED_EXPAND | LIB_TAG_DOIT;
602         }
603         else {
604                 id->tag &= ~(LIB_TAG_NEED_EXPAND | LIB_TAG_DOIT);
605         }
606 }
607
608 static void blendfile_write_partial_cb(void *UNUSED(handle), Main *UNUSED(bmain), void *vid)
609 {
610         if (vid) {
611                 ID *id = vid;
612                 /* only tag for need-expand if not done, prevents eternal loops */
613                 if ((id->tag & LIB_TAG_DOIT) == 0)
614                         id->tag |= LIB_TAG_NEED_EXPAND | LIB_TAG_DOIT;
615
616                 if (id->lib && (id->lib->id.tag & LIB_TAG_DOIT) == 0)
617                         id->lib->id.tag |= LIB_TAG_DOIT;
618         }
619 }
620
621 /**
622  * \return Success.
623  */
624 bool BKE_blendfile_write_partial(
625         Main *bmain_src, const char *filepath, const int write_flags, ReportList *reports)
626 {
627         Main *bmain_dst = MEM_callocN(sizeof(Main), "copybuffer");
628         ListBase *lbarray_dst[MAX_LIBARRAY], *lbarray_src[MAX_LIBARRAY];
629         int a, retval;
630
631         void     *path_list_backup = NULL;
632         const int path_list_flag = (BKE_BPATH_TRAVERSE_SKIP_LIBRARY | BKE_BPATH_TRAVERSE_SKIP_MULTIFILE);
633
634         /* This is needed to be able to load that file as a real one later
635          * (otherwise main->name will not be set at read time). */
636         BLI_strncpy(bmain_dst->name, bmain_src->name, sizeof(bmain_dst->name));
637
638         if (write_flags & G_FILE_RELATIVE_REMAP) {
639                 path_list_backup = BKE_bpath_list_backup(bmain_src, path_list_flag);
640         }
641
642         BLO_main_expander(blendfile_write_partial_cb);
643         BLO_expand_main(NULL, bmain_src);
644
645         /* move over all tagged blocks */
646         set_listbasepointers(bmain_src, lbarray_src);
647         a = set_listbasepointers(bmain_dst, lbarray_dst);
648         while (a--) {
649                 ID *id, *nextid;
650                 ListBase *lb_dst = lbarray_dst[a], *lb_src = lbarray_src[a];
651
652                 for (id = lb_src->first; id; id = nextid) {
653                         nextid = id->next;
654                         if (id->tag & LIB_TAG_DOIT) {
655                                 BLI_remlink(lb_src, id);
656                                 BLI_addtail(lb_dst, id);
657                         }
658                 }
659         }
660
661
662         /* save the buffer */
663         retval = BLO_write_file(bmain_dst, filepath, write_flags, reports, NULL);
664
665         /* move back the main, now sorted again */
666         set_listbasepointers(bmain_src, lbarray_dst);
667         a = set_listbasepointers(bmain_dst, lbarray_src);
668         while (a--) {
669                 ID *id;
670                 ListBase *lb_dst = lbarray_dst[a], *lb_src = lbarray_src[a];
671
672                 while ((id = BLI_pophead(lb_src))) {
673                         BLI_addtail(lb_dst, id);
674                         id_sort_by_name(lb_dst, id);
675                 }
676         }
677
678         MEM_freeN(bmain_dst);
679
680         if (path_list_backup) {
681                 BKE_bpath_list_restore(bmain_src, path_list_flag, path_list_backup);
682                 BKE_bpath_list_free(path_list_backup);
683         }
684
685         return retval;
686 }
687
688 void BKE_blendfile_write_partial_end(Main *bmain_src)
689 {
690         BKE_main_id_tag_all(bmain_src, LIB_TAG_NEED_EXPAND | LIB_TAG_DOIT, false);
691 }
692
693 /** \} */