0024887: Visualization - revise and extend Raytracing controls
[occt.git] / src / Graphic3d / Graphic3d.cdl
1 -- Created on: 1993-03-31
2 -- Created by: NW,JPB,CAL
3 -- Copyright (c) 1993-1999 Matra Datavision
4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
5 --
6 -- This file is part of Open CASCADE Technology software library.
7 --
8 -- This library is free software; you can redistribute it and/or modify it under
9 -- the terms of the GNU Lesser General Public License version 2.1 as published
10 -- by the Free Software Foundation, with special exception defined in the file
11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12 -- distribution for complete text of the license and disclaimer of any warranty.
13 --
14 -- Alternatively, this file may be used under the terms of Open CASCADE
15 -- commercial license or contractual agreement.
16
17 -- Package  :   Graphic3d
18 -- Updated  :   Vendredi 2 Octobre 1992
19 --          Mercredi 31 Mars 1993
20 --          Mercredi 19 Janvier 1994
21 --      1/08/97 ; PCT : Ajout texture mapping
22 --      11/97 ; CAL : retrait de la dependance avec math
23 --      11/97 ; CAL : retrait des DataStructure
24 --              04/98 ; FGU : ajout champs 'TOR_EMISSION'
25 --      16-09-98; BGN: (S3819) Ajout TypeOfTriedronEcho,
26 --                             TypeOfTriedronPosition.
27 --              22-09-98; BGN: S3989 (anciennement S3819): report
28 --                             dans Aspect des TypeOfTriedron*
29 --              26-03-99 : FMN ; Compatibilite ascendante:
30 --              Ajout des anciens noms de materiaux.
31 --              09-04-99 : GG ; Compatibilite ascendante:
32 --                         NameOfPhysicalMaterial disparait
33 --              23-11-99 : GG ; Add material name DEFAULT
34 --          16-06-2000 : ATS : Study G005: class ArrayOfPrimitives
35 --              and derivated used for model presentation.
36 --                       Required: enumeration TypeOfPrimitive;
37 --                  imported PrimitiveArray; class PrimitiveList.
38 --      17-12-01 : GG ; IMP171201 : Add material name UserDefined
39 --              Thanks to Stephane ROUTELOUS
40 --              20-01-2009 : ABD Integration support of system fonts (using FTGL and FreeType)
41 -- Objective    :   Specifications definitives
42
43 package Graphic3d
44
45     ---Version:
46
47     ---Purpose: This package permits the creation of 3d graphic objects
48     --      in a visualiser.
49     --      These objects, called structures, are composed of groups of
50     --      primitives and attributes.
51     --      The group is the smallest editable element of a structure.
52     --      A structure can be displayed, erased, high-lighted.
53     --      A transformation can be applied to it.
54     --      Structures can be connected to form a tree of structures,
55     --      composed by transformations.
56     --      The visualiser permits global manipulation of structures.
57
58     ---Keywords: Structure, Group, Primitives, Line, Marker, Text,
59     --  FillAreas, Vertex, Vector, Material, Font, Shading
60     ---Warning:
61     ---References:
62
63 uses
64
65     TCollection,
66     TColStd,
67     TColgp,
68     OSD,
69     Quantity,
70     Aspect,
71     MMgt,
72     WNT,
73     Image,
74     gp,
75     Font
76 is
77
78     -----------------------
79     -- Category: Exceptions
80     -----------------------
81
82     exception AspectTextDefinitionError inherits OutOfRange;
83     ---Category: Exceptions
84
85     exception CycleError inherits DomainError;
86     ---Category: Exceptions
87
88     exception GroupDefinitionError inherits OutOfRange;
89     ---Category: Exceptions
90
91     exception InitialisationError inherits OutOfRange;
92     ---Category: Exceptions
93
94     exception MaterialDefinitionError inherits OutOfRange;
95     ---Category: Exceptions
96
97     exception PlotterDefinitionError inherits OutOfRange;
98     ---Category: The exceptions
99
100     exception PriorityDefinitionError inherits OutOfRange;
101     ---Category: Exceptions
102
103     exception StructureDefinitionError inherits OutOfRange;
104     ---Category: Exceptions
105
106     exception TransformError inherits OutOfRange;
107     ---Category: Exceptions
108
109     exception VectorError inherits OutOfRange;
110     ---Category: Exceptions
111
112     -------------------------
113     -- Category: Enumerations
114     -------------------------
115
116         enumeration NameOfMaterial is
117                     NOM_BRASS,      -- laiton       (PHYSIC)
118                     NOM_BRONZE,     -- bronze       (PHYSIC)
119                     NOM_COPPER,     -- cuivre       (PHYSIC)
120                     NOM_GOLD,       -- or           (PHYSIC)
121
122                     NOM_PEWTER,     -- etain        (PHYSIC)
123
124                     NOM_PLASTER,    -- platre       (GENERIC)
125                     NOM_PLASTIC,    -- plastic      (GENERIC)
126
127                     NOM_SILVER,     -- argent       (PHYSIC)
128
129                     NOM_STEEL,      -- acier        (PHYSIC)
130
131                     NOM_STONE,      -- pierre       (PHYSIC)
132
133                     NOM_SHINY_PLASTIC,   -- plastique brillant   (GENERIC)
134                     NOM_SATIN,           --  satin        (GENERIC)
135                     NOM_METALIZED,       -- metallise New (GENERIC)
136                     NOM_NEON_GNC,        -- neon      New (GENERIC)
137                     NOM_CHROME,          -- chrome    New (PHYSIC)
138                     NOM_ALUMINIUM,       -- aluminium New (PHYSIC)
139                     NOM_OBSIDIAN,        -- obsidian  New (PHYSIC)
140                     NOM_NEON_PHC,        -- neon      New (PHYSIC)
141                     NOM_JADE,            -- jade      New (PHYSIC)
142
143                     NOM_CHARCOAL,
144
145                     NOM_WATER,
146                     NOM_GLASS,
147                     NOM_DIAMOND,
148
149                     NOM_DEFAULT,
150                     NOM_UserDefined -- owner material
151     end NameOfMaterial;
152     ---Purpose: Types of aspect materials.
153     ---Category: Enumerations
154
155     enumeration TypeOfMaterial is MATERIAL_ASPECT,          -- Materiel generique
156                                   MATERIAL_PHYSIC           -- Materiel physique
157     end TypeOfMaterial;
158         ---Purpose: Types of materials specifies if a material can change color.
159     ---Category: Enumerations
160
161         enumeration  NameOfTexture1D  is  NOT_1D_ELEVATION,
162                       NOT_1D_UNKNOWN
163     end  NameOfTexture1D;
164     ---Purpose: Types of standard textures.
165     ---Category: Enumerations
166
167
168     enumeration  NameOfTexture2D  is  NOT_2D_MATRA,
169                                       NOT_2D_ALIENSKIN,
170                                       NOT_2D_BLUE_ROCK,
171                                       NOT_2D_BLUEWHITE_PAPER,
172                                       NOT_2D_BRUSHED,
173                                       NOT_2D_BUBBLES,
174                                       NOT_2D_BUMP,
175                                       NOT_2D_CAST,
176                                       NOT_2D_CHIPBD,
177                                       NOT_2D_CLOUDS,
178                                       NOT_2D_FLESH,
179                                       NOT_2D_FLOOR,
180                                       NOT_2D_GALVNISD,
181                                       NOT_2D_GRASS,
182                                       NOT_2D_ALUMINUM,
183                                       NOT_2D_ROCK,
184                                       NOT_2D_KNURL,
185                                       NOT_2D_MAPLE,
186                                       NOT_2D_MARBLE,
187                                       NOT_2D_MOTTLED,
188                                       NOT_2D_RAIN,
189                                       NOT_2D_UNKNOWN
190     end  NameOfTexture2D;
191     ---Purpose: Types of standard textures.
192     ---Category: Enumerations
193
194
195         enumeration  NameOfTextureEnv is  NOT_ENV_CLOUDS,
196                                           NOT_ENV_CV,
197                                           NOT_ENV_MEDIT,
198                                           NOT_ENV_PEARL,
199                                           NOT_ENV_SKY1,
200                                           NOT_ENV_SKY2,
201                                           NOT_ENV_LINES,
202                                           NOT_ENV_ROAD,
203                                           NOT_ENV_UNKNOWN
204     end  NameOfTextureEnv;
205     ---Purpose: Types of standard textures.
206     ---Category: Enumerations
207
208         enumeration  TypeOfTexture  is  TOT_1D,
209                                         TOT_2D,
210                                         TOT_2D_MIPMAP;
211     ---Purpose: Type of the texture file format.
212     ---Category: Enumerations
213
214     enumeration  TypeOfTextureMode  is  TOTM_OBJECT,
215                                         TOTM_SPHERE,
216                                         TOTM_EYE,
217                                         TOTM_MANUAL,
218                                         TOTM_SPRITE;
219     ---Purpose: Type of the texture projection.
220     ---Category: Enumerations
221
222     enumeration  TypeOfTextureFilter is TOTF_NEAREST,
223                                         TOTF_BILINEAR,
224                                         TOTF_TRILINEAR;
225     ---Purpose: Type of the texture filter.
226     -- Notice that for textures without mipmaps linear interpolation will be used instead of TOTF_BILINEAR and TOTF_TRILINEAR.
227     ---Category: Enumerations
228
229     enumeration  LevelOfTextureAnisotropy is LOTA_OFF,
230                                              LOTA_FAST,
231                                              LOTA_MIDDLE,
232                                              LOTA_QUALITY;
233     ---Purpose: Level of anisotropy filter.
234     -- Notice that actual quality depends on hardware capabilities!
235     ---Category: Enumerations
236
237     enumeration  NameOfTexturePlane  is  NOTP_XY,
238                                          NOTP_YZ,
239                                          NOTP_ZX,
240                                          NOTP_UNKNOWN;
241     ---Purpose: Type of the texture projection plane for both S and T texture coordinate.
242     ---Category: Enumerations
243
244     enumeration TypeOfComposition is    TOC_REPLACE,
245                         TOC_POSTCONCATENATE
246     end TypeOfComposition;
247     ---Purpose: To manage the transformation matrices of structures.
248     ---Category: Enumerations
249
250     enumeration TypeOfConnection is TOC_ANCESTOR,
251                     TOC_DESCENDANT
252     end TypeOfConnection;
253     ---Purpose: To manage the connections between the structures.
254     ---Category: Enumerations
255
256     enumeration TypeOfPolygon is    TOP_UNKNOWN,
257                                     TOP_COMPLEX,
258                                     TOP_CONCAVE,
259                                     TOP_CONVEX
260     end TypeOfPolygon;
261     ---Purpose: The type of polygon in a group in a structure.
262     ---Category: Enumerations
263
264     enumeration TypeOfPrimitive is  TOP_UNDEFINED,
265                                     TOP_POLYLINE,
266                                     TOP_POLYGON,
267                                     TOP_TRIANGLEMESH,
268                                     TOP_QUADRANGLEMESH,
269                                     TOP_TEXT,
270                                     TOP_MARKER,
271                                     TOP_PARRAY
272     end TypeOfPrimitive;
273     ---Purpose: The type of primitive in a group in a structure.
274     ---Category: Enumerations
275
276         enumeration TypeOfPrimitiveArray is TOPA_UNDEFINED,
277                                             TOPA_POINTS,
278                                             TOPA_POLYLINES,
279                                             TOPA_SEGMENTS,
280                                             TOPA_POLYGONS,
281                                             TOPA_TRIANGLES,
282                                             TOPA_QUADRANGLES,
283                                             TOPA_TRIANGLESTRIPS,
284                                             TOPA_QUADRANGLESTRIPS,
285                                             TOPA_TRIANGLEFANS
286         end TypeOfPrimitiveArray;
287         ---Purpose: The type of primitive array in a group in a structure.
288         ---Category: Enumerations
289
290     enumeration TypeOfReflection is TOR_AMBIENT,
291                                     TOR_DIFFUSE,
292                                     TOR_SPECULAR,
293                                     TOR_EMISSION
294     end TypeOfReflection;
295     ---Purpose: Nature of the reflection of a material.
296     ---Category: Enumerations
297
298     enumeration TypeOfStructure is  TOS_WIREFRAME,
299                                     TOS_SHADING,
300                                     TOS_COMPUTED,
301                                     TOS_ALL
302     end TypeOfStructure;
303     ---Purpose: Structural attribute indicating if it can be displayed
304     --      in wireframe, shadow mode, or both.
305     ---Category: Enumerations
306
307     enumeration TextPath is TP_UP,
308                             TP_DOWN,
309                             TP_LEFT,
310                             TP_RIGHT
311     end TextPath;
312     ---Purpose: Direction in which text is displayed.
313     ---Category: Enumerations
314
315     enumeration HorizontalTextAlignment is  HTA_LEFT,
316                                             HTA_CENTER,
317                                             HTA_RIGHT
318     end HorizontalTextAlignment;
319     ---Purpose: Defines the horizontal position of the text
320     --      relative to its anchor.
321     ---Category: Enumerations
322
323     enumeration VerticalTextAlignment is    VTA_BOTTOM,
324                                             VTA_CENTER,
325                                             VTA_TOP
326     end VerticalTextAlignment;
327     ---Purpose: Defines the vertical position of the text
328     --      relative to its anchor.
329     ---Category: Enumerations
330
331     enumeration GroupAspect is ASPECT_LINE,
332         ASPECT_TEXT,
333         ASPECT_MARKER,
334         ASPECT_FILL_AREA
335     end GroupAspect;
336     ---Purpose: Identifies primitives aspects defined per group.
337     -- - ASPECT_LINE: aspect for line primitives;
338     -- - ASPECT_TEXT: aspect for text primitives;
339     -- - ASPECT_MARKER: aspect for marker primitives;
340     -- - ASPECT_FILL_AREA: aspect for face primitives.
341
342     enumeration RenderingMode is
343       RM_RASTERIZATION, RM_RAYTRACING
344     end RenderingMode;
345     ---Purpose: Describes rendering modes.
346     -- - RM_RASTERIZATION: enables OpenGL rasterization mode;
347     -- - RM_RAYTRACING: enables GPU ray-tracing mode.
348
349     ---------------------------
350     -- Category: Imported types
351     ---------------------------
352
353     imported Buffer;
354     imported Buffer_Handle;
355     imported BoundBuffer;
356     imported BoundBuffer_Handle;
357     imported IndexBuffer;
358     imported IndexBuffer_Handle;
359
360     imported BufferType;
361
362     imported CBitFields20;
363     ---Purpose: Defines the C structure
364     ---Category: Imported types
365
366     imported CBitFields16;
367     ---Purpose: Defines the C structure
368     ---Category: Imported types
369
370     imported CBitFields8;
371     ---Purpose: Defines the C structure
372     ---Category: Imported types
373
374     imported CBitFields4;
375     ---Purpose: Defines the C structure
376     ---Category: Imported types
377
378     imported CAspectFillArea;
379     imported CAspectMarker;
380     imported CAspectLine;
381     imported CAspectText;
382
383     imported CStructure;
384     ---Purpose: Defines the C structure <astructure>
385     ---Category: Imported types
386
387     pointer CStructurePtr to CStructure from Graphic3d;
388
389     imported CStructure_Handle;
390
391     imported CLight;
392     ---Purpose: Defines the C structure <alight>
393     ---Category: Imported types
394
395     imported CPick;
396     ---Purpose: Defines the C structure <apick>
397     ---Category: Imported types
398
399     imported CPlane;
400     ---Purpose: Defines the C structure <aplane>
401     ---Category: Imported types
402
403     imported CBounds;
404     ---Purpose: Defines the C structure <abounds>
405     ---Category: Imported types
406
407     imported CUserDraw;
408     ---Purpose: Defines the C structure <auserdraw>
409     ---Category: Imported types
410
411     imported CView;
412     ---Purpose: Defines the C structure <aview>
413     ---Category: Imported types
414     
415     imported RenderingParams;
416     ---Purpose: Describes rendering parameters and effects.
417     ---Category: Imported types
418
419     imported CGraduatedTrihedron;
420     ---Purpose: Defines the C structure of a graduated trihedron.
421     ---Category: Imported types
422
423     imported ClipPlane;
424     ---Purpose: Describes geometrical and auxiliary properties of clipping
425     -- planes applied on rendering by graphical driver.
426     ---Category: Imported types
427
428     imported ClipPlane_Handle;
429     ---Purpose: CDL-compatibility handle type definition for
430     -- clip plane objects.
431
432     imported CTexture;
433
434     imported CTransPersStruct;
435     imported TransModeFlags;
436     
437     imported MarkerImage;
438     imported MarkerImage_Handle;
439     imported Camera_Handle;
440
441     primitive PtrFrameBuffer;
442     primitive Vec2;
443     primitive Vec3;
444     primitive Vec4;
445     imported  Mat4;
446     imported  Mat4d;
447
448     imported ZLayerSettings;
449
450     --------------------
451     -- Category: Classes
452     --------------------
453
454     deferred class ArrayOfPrimitives;
455     ---Purpose: Contains basic methods for array allocation and filling
456
457     class ArrayOfPoints;
458     ---Purpose: Contains points array definition
459
460     class ArrayOfPolylines;
461     ---Purpose: Contains polylines array definition
462
463     class ArrayOfSegments;
464     ---Purpose: Contains segments array definition
465
466     class ArrayOfPolygons;
467     ---Purpose: Contains polygons array definition
468
469     class ArrayOfTriangles;
470     ---Purpose: Contains triangles array definition
471
472     class ArrayOfTriangleStrips;
473     ---Purpose: Contains triangles strip array definition
474
475     class ArrayOfTriangleFans;
476     ---Purpose: Contains triangles fan array definition
477
478     class ArrayOfQuadrangles;
479     ---Purpose: Contains quatrangles array definition
480
481     class ArrayOfQuadrangleStrips;
482     ---Purpose: Contains quadrangles strip array definition
483
484     class AspectLine3d;
485     ---Purpose: Grouping line attributes
486     ---Category: Classes
487
488     class AspectFillArea3d;
489     ---Purpose: Grouping face attributes
490     ---Category: Classes
491
492     class AspectMarker3d;
493     ---Purpose: Grouping marker attributes
494     ---Category: Classes
495
496     class AspectText3d;
497     ---Purpose: Grouping text attributes.
498     ---Category: Classes
499
500     deferred class Group;
501     ---Purpose: For grouping together primitives in a structure
502     ---Category: Classes
503
504     class MaterialAspect;
505     ---Purpose: Aspect attributes of a 3d face.
506     ---Category: Classes
507
508     class Structure;
509     ---Purpose: Graphic object.
510     ---Category: Classes
511
512     pointer StructurePtr to Structure from Graphic3d;
513
514     deferred class GraphicDriver;
515     ---Purpose: Defines a graphic driver for 3d interface
516
517     deferred class StructureManager;
518     ---Purpose: Visualiser with which the graphic objects are associated.
519     ---Category: Classes
520
521     pointer StructureManagerPtr to StructureManager from Graphic3d;
522
523     deferred class DataStructureManager;
524     ---Purpose: Visualiser with which the graphic objects are associated.
525     ---Category: Classes
526
527     deferred class Plotter;
528     ---Purpose: Defines the minimal plotter.
529     ---Category: The classes
530
531     class Vector;
532     ---Purpose: 3d vector
533     ---Category: Classes
534
535     imported Vertex;
536     ---Purpose: 3d vertex
537     ---Category: Classes
538
539     ---------------------------------
540     -- Category: Instantiated classes
541     ---------------------------------
542
543     imported SequenceOfGroup;
544
545     ---Category: Instantiated classes
546
547     class MapOfStructure instantiates
548             Map from TCollection (Structure from Graphic3d,MapTransientHasher from TColStd);
549
550
551     ---Category: Instantiated classes
552
553     class SequenceOfStructure instantiates
554             Sequence from TCollection
555             (Structure from Graphic3d);
556     ---Category: Instantiated classes
557
558     class HSequenceOfStructure instantiates
559             HSequence from TCollection
560         (Structure from Graphic3d, SequenceOfStructure from Graphic3d);
561     ---Category: Instantiated classes
562
563     class Array1OfVector instantiates
564             Array1 from TCollection (Vector from Graphic3d);
565     ---Category: Instantiated classes
566
567     class Array1OfVertex instantiates
568             Array1 from TCollection (Vertex from Graphic3d);
569     ---Category: Instantiated classes
570
571     class Array2OfVertex instantiates
572             Array2 from TCollection (Vertex from Graphic3d);
573     ---Category: Instantiated classes
574
575     class ListOfShortReal instantiates
576             List from TCollection (ShortReal from Standard);
577     ---Category: Instantiated classes
578
579     --ABD Integration support of system fonts (using FTGL and FreeType)
580     imported NListOfHAsciiString;
581     ---Category: Instantiated classes
582
583     imported ShaderProgram_Handle;
584     ---Category: Instantiated classes
585
586     imported SequenceOfHClipPlane;
587     ---Category: Instantiated classes
588     -- Sequence of handles on clip planes
589
590     deferred  class  TextureRoot  from  Graphic3d;
591     deferred  class  TextureMap   from  Graphic3d;
592     deferred  class  Texture1D    from  Graphic3d;
593     deferred  class  Texture2D    from  Graphic3d;
594
595     class  TextureParams    from  Graphic3d;
596     class  TextureEnv       from  Graphic3d;
597     class  Texture1Dmanual  from  Graphic3d;
598     class  Texture1Dsegment from  Graphic3d;
599     class  Texture2Dmanual  from  Graphic3d;
600     class  Texture2Dplane   from  Graphic3d;
601
602
603     enumeration ExportFormat is
604
605         EF_PostScript,
606         EF_EnhPostScript,
607         EF_TEX,
608         EF_PDF,
609         EF_SVG,
610         EF_PGF,
611         EF_EMF
612
613     end ExportFormat;
614
615
616     enumeration SortType is
617
618         ST_Simple,    -- sorting by depth of center point of primitive(fast)
619         ST_BSP_Tree   -- sorting by BSPTree (slow, but fine result )
620
621         end SortType;
622
623     ----------------------------
624     -- Category: Package methods
625     ----------------------------
626
627     InitGraphicDriver (theDisplayConnection: DisplayConnection_Handle from Aspect)
628        returns GraphicDriver from Graphic3d
629        raises  DriverDefinitionError from Aspect;
630     ---Purpose: Initialize graphic driver and returns Handle to it.
631
632     
633
634 end Graphic3d;