-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathdocumentation.html
6560 lines (6553 loc) · 285 KB
/
documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html" charset="utf-8">
<title>Intel OSPRay Documentation</title>
<link rel="stylesheet" type="text/css" media="screen" href="stylesheet.css">
<style type="text/css">
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { color: #008000; } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { color: #008000; font-weight: bold; } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
div.sourceCode { overflow-x: initial; }
</style>
</head>
<body>
<div id="header">
<div id="header-github">
<a id="forkme-banner" href="https://github.com/ospray/OSPRay">View on GitHub</a>
</div>
<div id="header-title">
Intel<sup>®</sup> OSPRay
</div>
<div id="header-navbar">
<ul>
<li><a href="index.html">Overview</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li id="selected"><a href="documentation.html">Documentation</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="gallery.html">Gallery</a></li>
<li><a href="https://github.com/ospray/OSPRay/issues">Bugs/Issues</a></li>
<li><a href="related_projects.html">Related Projects</a></li>
</ul>
</div>
<div id="header-spacing"></div>
</div>
<nav id="TOC" role="doc-toc">
<ul>
<li><a href="#documentation"
id="toc-documentation">Documentation</a></li>
<li><a href="#ospray-api" id="toc-ospray-api">OSPRay API</a>
<ul>
<li><a href="#initialization-and-shutdown"
id="toc-initialization-and-shutdown">Initialization and Shutdown</a>
<ul>
<li><a href="#command-line-arguments"
id="toc-command-line-arguments">Command Line Arguments</a></li>
<li><a href="#manual-device-instantiation"
id="toc-manual-device-instantiation">Manual Device
Instantiation</a></li>
<li><a href="#environment-variables"
id="toc-environment-variables">Environment Variables</a></li>
<li><a href="#error-handling-and-status-messages"
id="toc-error-handling-and-status-messages">Error Handling and Status
Messages</a></li>
<li><a href="#loading-ospray-extensions-at-runtime"
id="toc-loading-ospray-extensions-at-runtime">Loading OSPRay Extensions
at Runtime</a></li>
<li><a href="#shutting-down-ospray"
id="toc-shutting-down-ospray">Shutting Down OSPRay</a></li>
</ul></li>
<li><a href="#objects" id="toc-objects">Objects</a>
<ul>
<li><a href="#parameters" id="toc-parameters">Parameters</a></li>
<li><a href="#data" id="toc-data">Data</a></li>
</ul></li>
<li><a href="#volumes" id="toc-volumes">Volumes</a>
<ul>
<li><a href="#structured-regular-volume"
id="toc-structured-regular-volume">Structured Regular Volume</a></li>
<li><a href="#structured-spherical-volume"
id="toc-structured-spherical-volume">Structured Spherical
Volume</a></li>
<li><a href="#adaptive-mesh-refinement-amr-volume"
id="toc-adaptive-mesh-refinement-amr-volume">Adaptive Mesh Refinement
(AMR) Volume</a></li>
<li><a href="#unstructured-volume"
id="toc-unstructured-volume">Unstructured Volume</a></li>
<li><a href="#vdb-volume" id="toc-vdb-volume">VDB Volume</a></li>
<li><a href="#particle-volume" id="toc-particle-volume">Particle
Volume</a></li>
<li><a href="#transfer-function" id="toc-transfer-function">Transfer
Function</a></li>
<li><a href="#volumetricmodels"
id="toc-volumetricmodels">VolumetricModels</a></li>
</ul></li>
<li><a href="#geometries" id="toc-geometries">Geometries</a>
<ul>
<li><a href="#mesh" id="toc-mesh">Mesh</a></li>
<li><a href="#subdivision" id="toc-subdivision">Subdivision</a></li>
<li><a href="#spheres" id="toc-spheres">Spheres</a></li>
<li><a href="#curves" id="toc-curves">Curves</a></li>
<li><a href="#boxes" id="toc-boxes">Boxes</a></li>
<li><a href="#planes" id="toc-planes">Planes</a></li>
<li><a href="#isosurfaces" id="toc-isosurfaces">Isosurfaces</a></li>
<li><a href="#geometricmodels"
id="toc-geometricmodels">GeometricModels</a></li>
</ul></li>
<li><a href="#lights" id="toc-lights">Lights</a>
<ul>
<li><a href="#photometric-lights"
id="toc-photometric-lights">Photometric Lights</a></li>
<li><a href="#directional-light-distant-light"
id="toc-directional-light-distant-light">Directional Light / Distant
Light</a></li>
<li><a href="#point-light-sphere-light"
id="toc-point-light-sphere-light">Point Light / Sphere Light</a></li>
<li><a href="#spotlight-ring-light"
id="toc-spotlight-ring-light">Spotlight / Ring Light</a></li>
<li><a href="#quad-light" id="toc-quad-light">Quad Light</a></li>
<li><a href="#cylinder-light" id="toc-cylinder-light">Cylinder
Light</a></li>
<li><a href="#hdri-light" id="toc-hdri-light">HDRI Light</a></li>
<li><a href="#ambient-light" id="toc-ambient-light">Ambient
Light</a></li>
<li><a href="#sun-sky-light" id="toc-sun-sky-light">Sun-Sky
Light</a></li>
<li><a href="#emissive-objects" id="toc-emissive-objects">Emissive
Objects</a></li>
</ul></li>
<li><a href="#materials" id="toc-materials">Materials</a>
<ul>
<li><a href="#obj-material" id="toc-obj-material">OBJ Material</a></li>
<li><a href="#principled" id="toc-principled">Principled</a></li>
<li><a href="#carpaint" id="toc-carpaint">CarPaint</a></li>
<li><a href="#metal" id="toc-metal">Metal</a></li>
<li><a href="#alloy" id="toc-alloy">Alloy</a></li>
<li><a href="#glass" id="toc-glass">Glass</a></li>
<li><a href="#thinglass" id="toc-thinglass">ThinGlass</a></li>
<li><a href="#metallicpaint"
id="toc-metallicpaint">MetallicPaint</a></li>
<li><a href="#luminous" id="toc-luminous">Luminous</a></li>
</ul></li>
<li><a href="#texture" id="toc-texture">Texture</a>
<ul>
<li><a href="#texture2d" id="toc-texture2d">Texture2D</a></li>
<li><a href="#volume-texture" id="toc-volume-texture">Volume
Texture</a></li>
<li><a href="#texture-transformations"
id="toc-texture-transformations">Texture Transformations</a></li>
</ul></li>
<li><a href="#cameras" id="toc-cameras">Cameras</a>
<ul>
<li><a href="#perspective-camera"
id="toc-perspective-camera">Perspective Camera</a></li>
<li><a href="#orthographic-camera"
id="toc-orthographic-camera">Orthographic Camera</a></li>
<li><a href="#panoramic-camera" id="toc-panoramic-camera">Panoramic
Camera</a></li>
</ul></li>
<li><a href="#scene-hierarchy" id="toc-scene-hierarchy">Scene
Hierarchy</a>
<ul>
<li><a href="#groups" id="toc-groups">Groups</a></li>
<li><a href="#instances" id="toc-instances">Instances</a></li>
<li><a href="#world" id="toc-world">World</a></li>
</ul></li>
<li><a href="#renderers" id="toc-renderers">Renderers</a>
<ul>
<li><a href="#scivis-renderer" id="toc-scivis-renderer">SciVis
Renderer</a></li>
<li><a href="#ambient-occlusion-renderer"
id="toc-ambient-occlusion-renderer">Ambient Occlusion Renderer</a></li>
<li><a href="#path-tracer" id="toc-path-tracer">Path Tracer</a></li>
</ul></li>
<li><a href="#framebuffer" id="toc-framebuffer">Framebuffer</a>
<ul>
<li><a href="#image-operation" id="toc-image-operation">Image
Operation</a></li>
</ul></li>
<li><a href="#rendering" id="toc-rendering">Rendering</a>
<ul>
<li><a href="#asynchronous-rendering"
id="toc-asynchronous-rendering">Asynchronous Rendering</a></li>
<li><a href="#synchronous-rendering"
id="toc-synchronous-rendering">Synchronous Rendering</a></li>
<li><a href="#rendering-and-ospcommit"
id="toc-rendering-and-ospcommit">Rendering and ospCommit</a></li>
<li><a href="#picking" id="toc-picking">Picking</a></li>
</ul></li>
</ul></li>
<li><a href="#modules-and-devices" id="toc-modules-and-devices">Modules
and Devices</a>
<ul>
<li><a href="#cpu" id="toc-cpu">CPU</a></li>
<li><a href="#gpu-beta" id="toc-gpu-beta">GPU (Beta)</a>
<ul>
<li><a href="#known-issues" id="toc-known-issues">Known Issues</a></li>
</ul></li>
<li><a href="#distributed-rendering-with-mpi"
id="toc-distributed-rendering-with-mpi">Distributed Rendering with
MPI</a>
<ul>
<li><a href="#mpi-offload-rendering" id="toc-mpi-offload-rendering">MPI
Offload Rendering</a></li>
<li><a href="#mpi-distributed-rendering"
id="toc-mpi-distributed-rendering">MPI Distributed Rendering</a></li>
<li><a href="#interaction-with-user-modules"
id="toc-interaction-with-user-modules">Interaction with User
Modules</a></li>
</ul></li>
<li><a href="#multidevice" id="toc-multidevice">MultiDevice</a></li>
</ul></li>
</ul>
</nav>
<div id="content-wrap">
<div id="content-wtoc">
<h1 id="documentation">Documentation</h1>
<p>The following <a href="https://www.ospray.org/OSPRay_readme.pdf"
title="OSPRay Documentation">API documentation</a> of OSPRay can also be
found as a <a href="https://www.ospray.org/OSPRay_readme.pdf"
title="OSPRay Documentation">pdf document</a>.</p>
<p>For a deeper explanation of the concepts, design, features and
performance of OSPRay also have a look at the IEEE Vis 2016 paper “<a
href="https://www.ospray.org/talks/IEEEVis2016_OSPRay_paper.pdf">OSPRay
– A CPU Ray Tracing Framework for Scientific Visualization</a>” (49MB,
or get the <a
href="https://www.ospray.org/talks/IEEEVis2016_OSPRay_paper_small.pdf">smaller
version</a> 1.8MB). The <a
href="https://www.ospray.org/talks/IEEEVis2016_OSPRay_talk.pdf">slides
of the talk</a> (5.2MB) are also available.</p>
<h1 id="ospray-api">OSPRay API</h1>
<p>To access the OSPRay API you first need to include the OSPRay
header</p>
<div class="sourceCode" id="cb1"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im">"ospray/ospray.h"</span></span></code></pre></div>
<p>where the API is compatible with C99 and C++.</p>
<h2 id="initialization-and-shutdown">Initialization and Shutdown</h2>
<p>To use the API, OSPRay must be initialized with a “device”. A device
is the object which implements the API. Creating and initializing a
device can be done in either of two ways: command line arguments using
<code>ospInit</code> or manually instantiating a device and setting
parameters on it.</p>
<h3 id="command-line-arguments">Command Line Arguments</h3>
<p>The first is to do so by giving OSPRay the command line from
<code>main()</code> by calling</p>
<div class="sourceCode" id="cb2"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a>OSPError ospInit<span class="op">(</span><span class="dt">int</span> <span class="op">*</span>argc<span class="op">,</span> <span class="at">const</span> <span class="dt">char</span> <span class="op">**</span>argv<span class="op">);</span></span></code></pre></div>
<p>OSPRay parses (and removes) its known command line parameters from
your application’s <code>main</code> function. For an example see the <a
href="tutorials.html#osptutorial">tutorial</a>. For possible error codes
see section <a href="#error-handling-and-status-messages">Error Handling
and Status Messages</a>. It is important to note that the arguments
passed to <code>ospInit</code> are processed in order they are listed.
The following parameters (which are prefixed by convention with
“<code>--osp:</code>”) are understood:</p>
<table style="width:98%;">
<caption>Command line parameters accepted by OSPRay’s
<code>ospInit</code>.</caption>
<colgroup>
<col style="width: 53%" />
<col style="width: 44%" />
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Parameter</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;"><code>--osp:debug</code></td>
<td style="text-align: left;">enables various extra checks and debug
output, and disables multi-threading</td>
</tr>
<tr class="even">
<td
style="text-align: left;"><code>--osp:num-threads=<n></code></td>
<td style="text-align: left;">use <code>n</code> threads instead of per
default using all detected hardware threads</td>
</tr>
<tr class="odd">
<td
style="text-align: left;"><code>--osp:log-level=<str></code></td>
<td style="text-align: left;">set logging level; valid values (in order
of severity) are <code>none</code>, <code>error</code>,
<code>warning</code>, <code>info</code>, and <code>debug</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>--osp:warn-as-error</code></td>
<td style="text-align: left;">send <code>warning</code> and
<code>error</code> messages through the error callback, otherwise send
<code>warning</code> messages through the message callback; must have
sufficient <code>logLevel</code> to enable warnings</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>--osp:verbose</code></td>
<td style="text-align: left;">shortcut for
<code>--osp:log-level=info</code> and enable debug output on
<code>cout</code>, error output on <code>cerr</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>--osp:vv</code></td>
<td style="text-align: left;">shortcut for
<code>--osp:log-level=debug</code> and enable debug output on
<code>cout</code>, error output on <code>cerr</code></td>
</tr>
<tr class="odd">
<td
style="text-align: left;"><code>--osp:load-modules=<name>[,...]</code></td>
<td style="text-align: left;">load one or more modules during
initialization; equivalent to calling
<code>ospLoadModule(name)</code></td>
</tr>
<tr class="even">
<td
style="text-align: left;"><code>--osp:log-output=<dst></code></td>
<td style="text-align: left;">convenience for setting where status
messages go; valid values for <code>dst</code> are <code>cerr</code> and
<code>cout</code></td>
</tr>
<tr class="odd">
<td
style="text-align: left;"><code>--osp:error-output=<dst></code></td>
<td style="text-align: left;">convenience for setting where error
messages go; valid values for <code>dst</code> are <code>cerr</code> and
<code>cout</code></td>
</tr>
<tr class="even">
<td
style="text-align: left;"><code>--osp:device=<name></code></td>
<td style="text-align: left;">use <code>name</code> as the type of
device for OSPRay to create; e.g., <code>--osp:device=cpu</code> gives
you the default <code>cpu</code> device; Note if the device to be used
is defined in a module, remember to pass
<code>--osp:load-modules=<name></code> first</td>
</tr>
<tr class="odd">
<td
style="text-align: left;"><code>--osp:set-affinity=<n></code></td>
<td style="text-align: left;">if <code>1</code>, bind software threads
to hardware threads; <code>0</code> disables binding; default is
<code>0</code></td>
</tr>
<tr class="even">
<td
style="text-align: left;"><code>--osp:device-params=<param>:<value>[,...]</code></td>
<td style="text-align: left;">set one or more other device parameters;
equivalent to calling <code>ospDeviceSet*(param, value)</code></td>
</tr>
</tbody>
</table>
<h3 id="manual-device-instantiation">Manual Device Instantiation</h3>
<p>The second method of initialization is to explicitly create the
device and possibly set parameters. This method looks almost identical
to how other <a href="#objects">objects</a> are created and used by
OSPRay (described in later sections). The first step is to create the
device with</p>
<div class="sourceCode" id="cb3"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a>OSPDevice ospNewDevice<span class="op">(</span><span class="at">const</span> <span class="dt">char</span> <span class="op">*</span>type<span class="op">);</span></span></code></pre></div>
<p>where the <code>type</code> string maps to a specific device
implementation. OSPRay always provides the “<code>cpu</code>” device,
which maps to a fast, local CPU implementation. Other devices can also
be added through additional modules, such as distributed MPI device
implementations. See next Chapter for details.</p>
<p>Once a device is created, you can call</p>
<div class="sourceCode" id="cb4"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> ospDeviceSetParam<span class="op">(</span>OSPObject<span class="op">,</span> <span class="at">const</span> <span class="dt">char</span> <span class="op">*</span>id<span class="op">,</span> OSPDataType type<span class="op">,</span> <span class="at">const</span> <span class="dt">void</span> <span class="op">*</span>mem<span class="op">);</span></span></code></pre></div>
<p>to set parameters on the device. The semantics of setting parameters
is exactly the same as <code>ospSetParam</code>, which is documented
below in the <a href="#parameters">parameters</a> section. The following
parameters can be set on all devices:</p>
<table style="width:97%;">
<caption>Parameters shared by all devices.</caption>
<colgroup>
<col style="width: 11%" />
<col style="width: 32%" />
<col style="width: 53%" />
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Type</th>
<th style="text-align: left;">Name</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">int</td>
<td style="text-align: left;">numThreads</td>
<td style="text-align: left;">number of threads which OSPRay should
use</td>
</tr>
<tr class="even">
<td style="text-align: left;">bool</td>
<td style="text-align: left;">disableMipMapGeneration</td>
<td style="text-align: left;">disable the default generation of MIP maps
for textures (e.g., to save the additional memory needed)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">uint</td>
<td style="text-align: left;">logLevel</td>
<td style="text-align: left;">logging level; valid values (in order of
severity) are <code>OSP_LOG_NONE</code>, <code>OSP_LOG_ERROR</code>,
<code>OSP_LOG_WARNING</code>, <code>OSP_LOG_INFO</code>, and
<code>OSP_LOG_DEBUG</code></td>
</tr>
<tr class="even">
<td style="text-align: left;">string</td>
<td style="text-align: left;">logOutput</td>
<td style="text-align: left;">convenience for setting where status
messages go; valid values are <code>cerr</code> and
<code>cout</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;">string</td>
<td style="text-align: left;">errorOutput</td>
<td style="text-align: left;">convenience for setting where error
messages go; valid values are <code>cerr</code> and
<code>cout</code></td>
</tr>
<tr class="even">
<td style="text-align: left;">bool</td>
<td style="text-align: left;">debug</td>
<td style="text-align: left;">set debug mode; equivalent to
<code>logLevel=debug</code> and <code>numThreads=1</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;">bool</td>
<td style="text-align: left;">warnAsError</td>
<td style="text-align: left;">send <code>warning</code> and
<code>error</code> messages through the error callback, otherwise send
<code>warning</code> messages through the message callback; must have
sufficient <code>logLevel</code> to enable warnings</td>
</tr>
<tr class="even">
<td style="text-align: left;">bool</td>
<td style="text-align: left;">setAffinity</td>
<td style="text-align: left;">bind software threads to hardware threads
if set to 1; 0 disables binding omitting the parameter will let OSPRay
choose</td>
</tr>
</tbody>
</table>
<p>Once parameters are set on the created device, the device must be
committed with</p>
<div class="sourceCode" id="cb5"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> ospDeviceCommit<span class="op">(</span>OSPDevice<span class="op">);</span></span></code></pre></div>
<p>To use the newly committed device, you must call</p>
<div class="sourceCode" id="cb6"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> ospSetCurrentDevice<span class="op">(</span>OSPDevice<span class="op">);</span></span></code></pre></div>
<p>This then sets the given device as the object which will respond to
all other OSPRay API calls.</p>
<p>Device handle lifetimes are managed with two calls, the first which
increments the internal reference count to the given
<code>OSPDevice</code></p>
<div class="sourceCode" id="cb7"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> ospDeviceRetain<span class="op">(</span>OSPDevice<span class="op">)</span></span></code></pre></div>
<p>and the second which decrements the reference count</p>
<div class="sourceCode" id="cb8"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> ospDeviceRelease<span class="op">(</span>OSPDevice<span class="op">)</span></span></code></pre></div>
<p>Users can change parameters on the device after initialization (from
either method above), by calling</p>
<div class="sourceCode" id="cb9"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a>OSPDevice ospGetCurrentDevice<span class="op">();</span></span></code></pre></div>
<p>This function returns the handle to the device currently used to
respond to OSPRay API calls, where users can set/change parameters and
recommit the device. If changes are made to the device that is already
set as the current device, it does not need to be set as current again.
Note this API call will increment the ref count of the returned device
handle, so applications must use <code>ospDeviceRelease</code> when
finished using the handle to avoid leaking the underlying device object.
If there is no current device set, this will return an invalid
<code>NULL</code> handle.</p>
<p>When a device is created, its reference count is initially
<code>1</code>. When a device is set as the current device, it
internally has its reference count incremented. Note that
<code>ospDeviceRetain</code> and <code>ospDeviceRelease</code> should
only be used with reference counts that the application tracks: removing
reference held by the current set device should be handled by
<code>ospShutdown</code>. Thus, <code>ospDeviceRelease</code> should
only decrement the reference counts that come from
<code>ospNewDevice</code>, <code>ospGetCurrentDevice</code>, and the
number of explicit calls to <code>ospDeviceRetain</code>.</p>
<p>OSPRay allows applications to query runtime properties of a device in
order to do enhanced validation of what device was loaded at runtime.
The following function can be used to get these device-specific
properties (attributes about the device, not parameter values)</p>
<div class="sourceCode" id="cb10"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="dt">int64_t</span> ospDeviceGetProperty<span class="op">(</span>OSPDevice<span class="op">,</span> OSPDeviceProperty<span class="op">);</span></span></code></pre></div>
<p>It returns an integer value of the queried property and the following
properties can be provided as parameter:</p>
<div class="sourceCode" id="cb11"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a>OSP_DEVICE_VERSION</span>
<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a>OSP_DEVICE_VERSION_MAJOR</span>
<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a>OSP_DEVICE_VERSION_MINOR</span>
<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a>OSP_DEVICE_VERSION_PATCH</span>
<span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a>OSP_DEVICE_SO_VERSION</span></code></pre></div>
<h3 id="environment-variables">Environment Variables</h3>
<p>OSPRay’s generic device parameters can be overridden via environment
variables for easy changes to OSPRay’s behavior without needing to
change the application (variables are prefixed by convention with
“<code>OSPRAY_</code>”):</p>
<table style="width:97%;">
<caption>Environment variables interpreted by OSPRay.</caption>
<colgroup>
<col style="width: 30%" />
<col style="width: 66%" />
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Variable</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">OSPRAY_NUM_THREADS</td>
<td style="text-align: left;">equivalent to
<code>--osp:num-threads</code></td>
</tr>
<tr class="even">
<td style="text-align: left;">OSPRAY_LOG_LEVEL</td>
<td style="text-align: left;">equivalent to
<code>--osp:log-level</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSPRAY_LOG_OUTPUT</td>
<td style="text-align: left;">equivalent to
<code>--osp:log-output</code></td>
</tr>
<tr class="even">
<td style="text-align: left;">OSPRAY_ERROR_OUTPUT</td>
<td style="text-align: left;">equivalent to
<code>--osp:error-output</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSPRAY_DEBUG</td>
<td style="text-align: left;">equivalent to
<code>--osp:debug</code></td>
</tr>
<tr class="even">
<td style="text-align: left;">OSPRAY_WARN_AS_ERROR</td>
<td style="text-align: left;">equivalent to
<code>--osp:warn-as-error</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSPRAY_SET_AFFINITY</td>
<td style="text-align: left;">equivalent to
<code>--osp:set-affinity</code></td>
</tr>
<tr class="even">
<td style="text-align: left;">OSPRAY_LOAD_MODULES</td>
<td style="text-align: left;">equivalent to
<code>--osp:load-modules</code>, can be a comma separated list of
modules which will be loaded in order</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSPRAY_DEVICE</td>
<td style="text-align: left;">equivalent to
<code>--osp:device:</code></td>
</tr>
</tbody>
</table>
<p>Note that these environment variables take precedence over values
specified through <code>ospInit</code> or manually set device
parameters.</p>
<h3 id="error-handling-and-status-messages">Error Handling and Status
Messages</h3>
<p>The following errors are currently used by OSPRay:</p>
<table>
<caption>Possible error codes, i.e., valid named constants of type
<code>OSPError</code>.</caption>
<thead>
<tr class="header">
<th style="text-align: left;">Name</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">OSP_NO_ERROR</td>
<td style="text-align: left;">no error occurred</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_UNKNOWN_ERROR</td>
<td style="text-align: left;">an unknown error occurred</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_INVALID_ARGUMENT</td>
<td style="text-align: left;">an invalid argument was specified</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_INVALID_OPERATION</td>
<td style="text-align: left;">the operation is not allowed for the
specified object</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_OUT_OF_MEMORY</td>
<td style="text-align: left;">there is not enough memory to execute the
command</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_UNSUPPORTED_CPU</td>
<td style="text-align: left;">the CPU is not supported (minimum ISA is
SSE4.1 on x86_64 and NEON on ARM64)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_VERSION_MISMATCH</td>
<td style="text-align: left;">a module could not be loaded due to
mismatching version</td>
</tr>
</tbody>
</table>
<p>These error codes are either directly return by some API functions,
or are recorded to be later queried by the application via</p>
<div class="sourceCode" id="cb12"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a>OSPError ospDeviceGetLastErrorCode<span class="op">(</span>OSPDevice<span class="op">);</span></span></code></pre></div>
<p>A more descriptive error message can be queried by calling</p>
<div class="sourceCode" id="cb13"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="at">const</span> <span class="dt">char</span><span class="op">*</span> ospDeviceGetLastErrorMsg<span class="op">(</span>OSPDevice<span class="op">);</span></span></code></pre></div>
<p>Alternatively, the application can also register a callback function
of type</p>
<div class="sourceCode" id="cb14"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">typedef</span> <span class="dt">void</span> <span class="op">(*</span>OSPErrorCallback<span class="op">)(</span><span class="dt">void</span> <span class="op">*</span>userData<span class="op">,</span> OSPError<span class="op">,</span> <span class="at">const</span> <span class="dt">char</span><span class="op">*</span> errorDetails<span class="op">);</span></span></code></pre></div>
<p>via</p>
<div class="sourceCode" id="cb15"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> ospDeviceSetErrorCallback<span class="op">(</span>OSPDevice<span class="op">,</span> OSPErrorCallback<span class="op">,</span> <span class="dt">void</span> <span class="op">*</span>userData<span class="op">);</span></span></code></pre></div>
<p>to get notified when errors occur.</p>
<p>Applications may be interested in messages which OSPRay emits,
whether for debugging or logging events. Applications can call</p>
<div class="sourceCode" id="cb16"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> ospDeviceSetStatusCallback<span class="op">(</span>OSPDevice<span class="op">,</span> OSPStatusCallback<span class="op">,</span> <span class="dt">void</span> <span class="op">*</span>userData<span class="op">);</span></span></code></pre></div>
<p>in order to register a callback function of type</p>
<div class="sourceCode" id="cb17"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">typedef</span> <span class="dt">void</span> <span class="op">(*</span>OSPStatusCallback<span class="op">)(</span><span class="dt">void</span> <span class="op">*</span>userData<span class="op">,</span> <span class="at">const</span> <span class="dt">char</span><span class="op">*</span> messageText<span class="op">);</span></span></code></pre></div>
<p>which OSPRay will use to emit status messages. By default, OSPRay
uses a callback which does nothing, so any output desired by an
application will require that a callback is provided. Note that
callbacks for C++ <code>std::cout</code> and <code>std::cerr</code> can
be alternatively set through <code>ospInit</code> or the
<code>OSPRAY_LOG_OUTPUT</code> environment variable.</p>
<p>Applications can clear either callback by passing <code>NULL</code>
instead of an actual function pointer.</p>
<h3 id="loading-ospray-extensions-at-runtime">Loading OSPRay Extensions
at Runtime</h3>
<p>OSPRay’s functionality can be extended via plugins (which we call
“modules”), which are implemented in shared libraries. To load module
<code>name</code> from <code>libospray_module_<name>.so</code> (on
Linux and Mac OS X) or <code>ospray_module_<name>.dll</code> (on
Windows) use</p>
<div class="sourceCode" id="cb18"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a>OSPError ospLoadModule<span class="op">(</span><span class="at">const</span> <span class="dt">char</span> <span class="op">*</span>name<span class="op">);</span></span></code></pre></div>
<p>Modules are searched in OS-dependent paths.
<code>ospLoadModule</code> returns <code>OSP_NO_ERROR</code> if the
plugin could be successfully loaded.</p>
<h3 id="shutting-down-ospray">Shutting Down OSPRay</h3>
<p>When the application is finished using OSPRay (typically on
application exit), the OSPRay API should be finalized with</p>
<div class="sourceCode" id="cb19"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> ospShutdown<span class="op">();</span></span></code></pre></div>
<p>This API call ensures that the current device is cleaned up
appropriately. Due to static object allocation having non-deterministic
ordering, it is recommended that applications call
<code>ospShutdown</code> before the calling application process
terminates.</p>
<h2 id="objects">Objects</h2>
<p>All entities of OSPRay (the <a
href="documentation.html#renderers">renderer</a>, <a
href="#volumes">volumes</a>, <a href="#geometries">geometries</a>, <a
href="#lights">lights</a>, <a href="#cameras">cameras</a>, …) are a
logical specialization of <code>OSPObject</code> and share common
mechanism to deal with parameters and lifetime.</p>
<p>An important aspect of object parameters is that parameters do not
get passed to objects immediately. Instead, parameters are not visible
at all to objects until they get explicitly committed to a given object
via a call to</p>
<div class="sourceCode" id="cb20"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> ospCommit<span class="op">(</span>OSPObject<span class="op">);</span></span></code></pre></div>
<p>at which time all previously additions or changes to parameters are
visible at the same time. If a user wants to change the state of an
existing object (e.g., to change the origin of an already existing
camera) it is perfectly valid to do so, as long as the changed
parameters are recommitted.</p>
<p>The commit semantic allow for batching up multiple small changes, and
specifies exactly when changes to objects will occur. This can impact
performance and consistency for devices crossing a PCI bus or across a
network.</p>
<p>Note that OSPRay uses reference counting to manage the lifetime of
all objects, so one cannot explicitly “delete” any object. Instead, to
indicate that the application does not need and does not access the
given object anymore, call</p>
<div class="sourceCode" id="cb21"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> ospRelease<span class="op">(</span>OSPObject<span class="op">);</span></span></code></pre></div>
<p>This decreases its reference count and if the count reaches
<code>0</code> the object will automatically get deleted. Passing
<code>NULL</code> is not an error. Note that every handle returned via
the API needs to be released when the object is no longer needed, to
avoid memory leaks.</p>
<p>Sometimes applications may want to have more than one reference to an
object, where it is desirable for the application to increment the
reference count of an object. This is done with</p>
<div class="sourceCode" id="cb22"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> ospRetain<span class="op">(</span>OSPObject<span class="op">);</span></span></code></pre></div>
<p>It is important to note that this is only necessary if the
application wants to call <code>ospRelease</code> on an object more than
once: objects which contain other objects as parameters internally
increment/decrement ref counts and should not be explicitly done by the
application.</p>
<h3 id="parameters">Parameters</h3>
<p>Parameters allow to configure the behavior of and to pass data to
objects. However, objects do <em>not</em> have an explicit interface for
reasons of high flexibility and a more stable compile-time API. Instead,
parameters are passed separately to objects in an arbitrary order, and
unknown parameters will simply be ignored (though a warning message will
be posted). The following function allows adding various types of
parameters with name <code>id</code> to a given object:</p>
<div class="sourceCode" id="cb23"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> ospSetParam<span class="op">(</span>OSPObject<span class="op">,</span> <span class="at">const</span> <span class="dt">char</span> <span class="op">*</span>id<span class="op">,</span> OSPDataType type<span class="op">,</span> <span class="at">const</span> <span class="dt">void</span> <span class="op">*</span>mem<span class="op">);</span></span></code></pre></div>
<p>The valid parameter names for all <code>OSPObject</code>s and what
types are valid are discussed in future sections.</p>
<p>Note that <code>mem</code> must always be a pointer <em>to</em> the
object, otherwise accidental type casting can occur. This is especially
true for pointer types (<code>OSP_VOID_PTR</code> and
<code>OSPObject</code> handles), as they will implicitly cast to
<code>void\ *</code>, but be incorrectly interpreted. To help with some
of these issues, there also exist variants of <code>ospSetParam</code>
for specific types, such as <code>ospSetInt</code> and
<code>ospSetVec3f</code> in the OSPRay utility library (found in
<code>ospray_util.h</code>). Note that half precision float parameters
<code>OSP_HALF, OSP_VEC[234]H</code> are not supported.</p>
<p>Users can also remove parameters that have been explicitly set from
<code>ospSetParam</code>. Any parameters which have been removed will go
back to their default value during the next commit unless a new
parameter was set after the parameter was removed. To remove a
parameter, use</p>
<div class="sourceCode" id="cb24"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> ospRemoveParam<span class="op">(</span>OSPObject<span class="op">,</span> <span class="at">const</span> <span class="dt">char</span> <span class="op">*</span>id<span class="op">);</span></span></code></pre></div>
<h3 id="data">Data</h3>
<p>OSPRay consumes data arrays from the application using a specific
object type, <code>OSPData</code>. There are several components to
describing a data array: element type, 1/2/3 dimensional striding, and
whether the array is shared with the application or copied into opaque,
OSPRay-owned memory.</p>
<p>Shared data arrays require that the application’s array memory
outlives the lifetime of the created <code>OSPData</code>, as OSPRay is
referring to application memory. Where this is not preferable,
applications use opaque arrays to allow the <code>OSPData</code> to own
the lifetime of the array memory. However, opaque arrays dictate the
cost of copying data into it, which should be kept in mind.</p>
<p>Thus, the most efficient way to specify a data array from the
application is to created a shared data array, which is done with</p>
<div class="sourceCode" id="cb25"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a>OSPData ospNewSharedData<span class="op">(</span><span class="at">const</span> <span class="dt">void</span> <span class="op">*</span>sharedData<span class="op">,</span></span>
<span id="cb25-2"><a href="#cb25-2" aria-hidden="true" tabindex="-1"></a> OSPDataType<span class="op">,</span></span>
<span id="cb25-3"><a href="#cb25-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">uint64_t</span> numItems1<span class="op">,</span></span>
<span id="cb25-4"><a href="#cb25-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">int64_t</span> byteStride1 <span class="op">=</span> <span class="dv">0</span><span class="op">,</span></span>
<span id="cb25-5"><a href="#cb25-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">uint64_t</span> numItems2 <span class="op">=</span> <span class="dv">1</span><span class="op">,</span></span>
<span id="cb25-6"><a href="#cb25-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">int64_t</span> byteStride2 <span class="op">=</span> <span class="dv">0</span><span class="op">,</span></span>
<span id="cb25-7"><a href="#cb25-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">uint64_t</span> numItems3 <span class="op">=</span> <span class="dv">1</span><span class="op">,</span></span>
<span id="cb25-8"><a href="#cb25-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">int64_t</span> byteStride3 <span class="op">=</span> <span class="dv">0</span><span class="op">,</span></span>
<span id="cb25-9"><a href="#cb25-9" aria-hidden="true" tabindex="-1"></a> OSPDeleterCallback <span class="op">=</span> NULL<span class="op">,</span></span>
<span id="cb25-10"><a href="#cb25-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">void</span> <span class="op">*</span>userData <span class="op">=</span> NULL<span class="op">);</span></span></code></pre></div>
<p>The call returns an <code>OSPData</code> handle to the created array.
The calling program guarantees that the <code>sharedData</code> pointer
will remain valid for the duration that this data array is being used.
The number of elements <code>numItems</code> must be positive (there
cannot be an empty data object). The data is arranged in three
dimensions, with specializations to two or one dimension (if some
<code>numItems</code> are 1). The distance between consecutive elements
(per dimension) is given in bytes with <code>byteStride</code> and can
also be negative. If <code>byteStride</code> is zero it will be
determined automatically (e.g., as <code>sizeof(type)</code>). Strides
do not need to be ordered, i.e., <code>byteStride2</code> can be smaller
than <code>byteStride1</code>, which is equivalent to a transpose.
However, if the stride should be calculated, then an ordering in
dimensions is assumed to disambiguate, i.e.,
<code>byteStride1 < byteStride2 < byteStride3</code>.</p>
<p>An application can pass ownership of shared data to OSPRay (for
example, when it temporarily created a modified version of its data only
to make it compatible with OSPRay) by providing a deleter function that
OSPRay will call whenever the time comes to deallocate the shared
buffer. The deleter function has the following signature:</p>
<div class="sourceCode" id="cb26"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb26-1"><a href="#cb26-1" aria-hidden="true" tabindex="-1"></a><span class="kw">typedef</span> <span class="dt">void</span> <span class="op">(*</span>OSPDeleterCallback<span class="op">)(</span><span class="at">const</span> <span class="dt">void</span> <span class="op">*</span>userData<span class="op">,</span> <span class="at">const</span> <span class="dt">void</span> <span class="op">*</span>sharedData<span class="op">);</span></span></code></pre></div>
<p>where <code>sharedData</code> will receive the address of the buffer
and <code>userData</code> will receive whatever additional state the
function needs to perform the deletion (both provided to
<code>ospNewSharedData</code> when sharing the data with OSPRay).</p>
<p>The enum type <code>OSPDataType</code> describes the different
element types that can be represented in OSPRay; valid constants are
listed in the table below.</p>
<table style="width:97%;">
<caption>Valid named constants for <code>OSPDataType</code>.</caption>
<colgroup>
<col style="width: 33%" />
<col style="width: 63%" />
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Type / Name</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">OSP_DEVICE</td>
<td style="text-align: left;">API device object reference</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_DATA</td>
<td style="text-align: left;">data reference</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_OBJECT</td>
<td style="text-align: left;">generic object reference</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_CAMERA</td>
<td style="text-align: left;">camera object reference</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_FRAMEBUFFER</td>
<td style="text-align: left;">framebuffer object reference</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_FUTURE</td>
<td style="text-align: left;">future object reference</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_LIGHT</td>
<td style="text-align: left;">light object reference</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_MATERIAL</td>
<td style="text-align: left;">material object reference</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_TEXTURE</td>
<td style="text-align: left;">texture object reference</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_RENDERER</td>
<td style="text-align: left;">renderer object reference</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_WORLD</td>
<td style="text-align: left;">world object reference</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_GROUP</td>
<td style="text-align: left;">group object reference</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_INSTANCE</td>
<td style="text-align: left;">instance object reference</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_GEOMETRY</td>
<td style="text-align: left;">geometry object reference</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_GEOMETRIC_MODEL</td>
<td style="text-align: left;">geometric model object reference</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_VOLUME</td>
<td style="text-align: left;">volume object reference</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_VOLUMETRIC_MODEL</td>
<td style="text-align: left;">volumetric model object reference</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_TRANSFER_FUNCTION</td>
<td style="text-align: left;">transfer function object reference</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_IMAGE_OPERATION</td>
<td style="text-align: left;">image operation object reference</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_STRING</td>
<td style="text-align: left;">C-style zero-terminated character
string</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_BOOL</td>
<td style="text-align: left;">8 bit boolean</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_CHAR, OSP_VEC[234]C</td>
<td style="text-align: left;">8 bit signed character scalar and
[234]-element vector</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_UCHAR, OSP_VEC[234]UC</td>
<td style="text-align: left;">8 bit unsigned character scalar and
[234]-element vector</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_SHORT, OSP_VEC[234]S</td>
<td style="text-align: left;">16 bit unsigned integer scalar and
[234]-element vector</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_USHORT, OSP_VEC[234]US</td>
<td style="text-align: left;">16 bit unsigned integer scalar and
[234]-element vector</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_INT, OSP_VEC[234]I</td>
<td style="text-align: left;">32 bit signed integer scalar and
[234]-element vector</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_UINT, OSP_VEC[234]UI</td>
<td style="text-align: left;">32 bit unsigned integer scalar and
[234]-element vector</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_LONG, OSP_VEC[234]L</td>
<td style="text-align: left;">64 bit signed integer scalar and
[234]-element vector</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_ULONG, OSP_VEC[234]UL</td>
<td style="text-align: left;">64 bit unsigned integer scalar and
[234]-element vector</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_HALF, OSP_VEC[234]H</td>
<td style="text-align: left;">16 bit half precision floating-point
scalar and [234]-element vector (IEEE 754 <code>binary16</code>)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_FLOAT, OSP_VEC[234]F</td>
<td style="text-align: left;">32 bit single precision floating-point
scalar and [234]-element vector</td>
</tr>
<tr class="even">
<td style="text-align: left;">OSP_DOUBLE, OSP_VEC[234]D</td>
<td style="text-align: left;">64 bit double precision floating-point
scalar and [234]-element vector</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OSP_BOX[1234]I</td>