1 -- Created on: 1997-01-28
3 -- Copyright (c) 1997-1999 Matra Datavision
4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
6 -- This file is part of Open CASCADE Technology software library.
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.
14 -- Alternatively, this file may be used under the terms of Open CASCADE
15 -- commercial license or contractual agreement.
17 deferred class GraphicDriver from Graphic3d inherits TShared
21 ---Purpose: This class allows the definition of a graphic driver
22 -- for 3d interface (currently only OpenGl driver is used).
31 Array1OfInteger from TColStd,
32 Array1OfReal from TColStd,
33 Array2OfReal from TColStd,
35 AsciiString from TCollection,
36 ExtendedString from TCollection,
38 NameOfColor from Quantity,
41 PlaneAngle from Quantity,
45 Array1OfEdge from Aspect,
47 TypeOfTriedronEcho from Aspect,
48 TypeOfTriedronPosition from Aspect,
51 PrintAlgo from Aspect,
52 DisplayConnection_Handle from Aspect,
54 ZLayerSettings from Graphic3d,
56 AspectLine3d from Graphic3d,
57 AspectMarker3d from Graphic3d,
58 AspectText3d from Graphic3d,
59 AspectFillArea3d from Graphic3d,
60 HorizontalTextAlignment from Graphic3d,
61 CBitFields20 from Graphic3d,
63 CLight from Graphic3d,
65 CPlane from Graphic3d,
66 CStructure from Graphic3d,
67 CStructure_Handle from Graphic3d,
69 BufferType from Graphic3d,
70 Structure from Graphic3d,
71 StructureManager from Graphic3d,
72 TextPath from Graphic3d,
73 TypeOfComposition from Graphic3d,
74 TypeOfPrimitive from Graphic3d,
75 Vector from Graphic3d,
76 Array1OfVertex from Graphic3d,
77 Array2OfVertex from Graphic3d,
78 Vertex from Graphic3d,
79 VerticalTextAlignment from Graphic3d,
80 PtrFrameBuffer from Graphic3d,
81 HArray1OfByte from TColStd,
82 FillMethod from Aspect,
83 GradientFillMethod from Aspect,
84 ExportFormat from Graphic3d,
85 SortType from Graphic3d,
86 HArray1OfReal from TColStd,
87 CUserDraw from Graphic3d,
88 NListOfHAsciiString from Graphic3d,
90 CGraduatedTrihedron from Graphic3d,
91 ClipPlane from Graphic3d,
96 TransformError from Graphic3d
99 Initialize (theDisp : DisplayConnection_Handle from Aspect)
100 returns GraphicDriver from Graphic3d;
102 ---Purpose: Initialises the Driver
104 ----------------------------
105 -- Category: Inquire methods
106 ----------------------------
108 InquireLightLimit ( me : mutable )
109 returns Integer from Standard
111 ---Purpose: call_togl_inquirelight
113 InquirePlaneLimit ( me : mutable )
114 returns Integer from Standard
116 ---Purpose: call_togl_inquireplane
118 InquireViewLimit ( me : mutable )
119 returns Integer from Standard
121 ---Purpose: call_togl_inquireview
123 -----------------------------------------
124 -- Category: Structure management methods
125 -----------------------------------------
127 DisplayStructure ( me : mutable;
128 theCView : CView from Graphic3d;
129 theCStructure : in out CStructure from Graphic3d;
130 thePriority : Integer from Standard )
132 ---Purpose: call_togl_displaystructure
134 EraseStructure ( me : mutable;
135 theCView : CView from Graphic3d;
136 theCStructure : in out CStructure from Graphic3d )
138 ---Purpose: call_togl_erasestructure
140 RemoveStructure ( me : mutable;
141 theCStructure : in out CStructure_Handle from Graphic3d )
143 ---Purpose: call_togl_removestructure
145 Structure (me : mutable;
146 theManager : StructureManager from Graphic3d)
147 returns CStructure_Handle from Graphic3d
149 ---Purpose: Creates new empty graphic structure
151 ------------------------------------
152 -- Category: Structured mode methods
153 ------------------------------------
155 ActivateView ( me : mutable;
156 ACView : CView from Graphic3d )
158 ---Purpose: call_togl_activateview
160 AntiAliasing ( me : mutable;
161 ACView : CView from Graphic3d;
162 AFlag : Boolean from Standard )
164 ---Purpose: call_togl_antialiasing
166 Background ( me : mutable;
167 ACView : CView from Graphic3d )
169 ---Purpose: call_togl_background
171 GradientBackground ( me : mutable;
172 ACView : CView from Graphic3d;
173 AColor1: Color from Quantity;
174 AColor2: Color from Quantity;
175 FillStyle : GradientFillMethod from Aspect
178 ---Purpose: call_togl_gradient_background
181 BackgroundImage( me : mutable;
182 FileName : CString from Standard;
183 ACView : CView from Graphic3d;
184 FillStyle : FillMethod from Aspect )
187 SetBgImageStyle( me : mutable;
188 ACView : CView from Graphic3d;
189 FillStyle : FillMethod from Aspect )
192 SetBgGradientStyle( me : mutable;
193 ACView : CView from Graphic3d;
194 FillStyle : GradientFillMethod from Aspect )
197 ClipLimit ( me : mutable;
198 ACView : CView from Graphic3d;
199 AWait : Boolean from Standard )
201 ---Purpose: call_togl_cliplimit
203 DeactivateView ( me : mutable;
204 ACView : CView from Graphic3d )
206 ---Purpose: call_togl_deactivateview
208 DepthCueing ( me : mutable;
209 ACView : CView from Graphic3d;
210 AFlag : Boolean from Standard )
212 ---Purpose: call_togl_cliplimit
214 RatioWindow ( me : mutable;
215 ACView : CView from Graphic3d )
217 ---Purpose: call_togl_ratio_window
219 Redraw ( me : mutable;
220 theCView : CView from Graphic3d;
221 theCUnderLayer : CLayer2d from Aspect;
222 theCOverLayer : CLayer2d from Aspect;
225 theWidth : Integer = 0;
226 theHeight : Integer = 0 )
228 ---Purpose: Redraw content of the view
230 RedrawImmediate ( me : mutable;
231 theCView : CView from Graphic3d;
232 theCUnderLayer : CLayer2d from Aspect;
233 theCOverLayer : CLayer2d from Aspect )
235 ---Purpose: Redraw layer of immediate presentations
237 Invalidate ( me : mutable;
238 theCView : CView from Graphic3d )
240 ---Purpose: Invalidates content of the view but does not redraw it
242 RemoveView ( me : mutable;
243 ACView : CView from Graphic3d )
245 ---Purpose: call_togl_removeview
247 SetLight ( me : mutable;
248 ACView : CView from Graphic3d )
250 ---Purpose: call_togl_setlight
252 SetClipPlanes (me : mutable; theCView : CView from Graphic3d) is deferred;
253 ---Purpose: Pass clip planes to the associated graphic driver view.
255 SetCamera (me : mutable; theCView : CView from Graphic3d)
257 ---Purpose: Inform graphic driver if camera assigned to view changes.
259 SetVisualisation ( me : mutable;
260 ACView : CView from Graphic3d )
262 ---Purpose: call_togl_setvisualisation
264 Transparency ( me : mutable;
265 ACView : CView from Graphic3d;
266 AFlag : Boolean from Standard )
268 ---Purpose: call_togl_transparency
271 ACView : in out CView from Graphic3d )
272 returns Boolean from Standard
274 ---Purpose: call_togl_view
276 Environment ( me : mutable;
277 ACView : CView from Graphic3d )
281 ----------------------------------------
282 ---Category: Methods to create Triangle
283 -- for Purpose : see Graphic3d_Group.cdl
284 ----------------------------------------
286 EnableVBO( me : mutable;
287 status : Boolean from Standard )
289 ---Purpose: enables/disables usage of OpenGL vertex buffer arrays while drawing primitiev arrays
292 theFreeBytes : out Size from Standard;
293 theInfo : out AsciiString from TCollection) returns Boolean from Standard is deferred;
294 ---Purpose: Returns information about GPU memory usage.
296 ----------------------------------------
297 ---Category: Methods to create Triedron
298 -- for Purpose : see Graphic3d_Group.cdl
299 ----------------------------------------
301 ZBufferTriedronSetup ( me : mutable;
302 XColor : NameOfColor from Quantity = Quantity_NOC_RED;
303 YColor : NameOfColor from Quantity = Quantity_NOC_GREEN;
304 ZColor : NameOfColor from Quantity = Quantity_NOC_BLUE1;
305 SizeRatio : Real from Standard = 0.8;
306 AxisDiametr : Real from Standard = 0.05;
307 NbFacettes : Integer from Standard = 12)
309 ---Purpose: call_togl_ztriedron_setup
311 TriedronDisplay ( me : mutable;
312 ACView : CView from Graphic3d;
313 APosition : TypeOfTriedronPosition from Aspect = Aspect_TOTP_CENTER;
314 AColor : NameOfColor from Quantity = Quantity_NOC_WHITE ;
315 AScale : Real from Standard = 0.02;
316 AsWireframe : Boolean from Standard = Standard_True )
318 ---Purpose: call_togl_triedron_display
321 TriedronErase ( me : mutable;
322 ACView : CView from Graphic3d)
324 ---Purpose: call_togl_triedron_erase
327 TriedronEcho ( me : mutable;
328 ACView : CView from Graphic3d;
329 AType : TypeOfTriedronEcho from Aspect = Aspect_TOTE_NONE )
331 ---Purpose: call_togl_triedron_echo
333 ---------------------------------
334 ---Category: Graduated trihedron
335 ---------------------------------
337 GraduatedTrihedronDisplay(me : mutable;
338 view : CView from Graphic3d;
339 cubic : CGraduatedTrihedron from Graphic3d)
340 ---Purpose: call_togl_graduatedtrihedron_display
343 GraduatedTrihedronErase(me : mutable;
344 view : CView from Graphic3d)
345 ---Purpose: call_togl_graduatedtrihedron_erase
348 GraduatedTrihedronMinMaxValues(me : mutable;
349 xmin : ShortReal from Standard;
350 ymin : ShortReal from Standard;
351 zmin : ShortReal from Standard;
352 xmax : ShortReal from Standard;
353 ymax : ShortReal from Standard;
354 zmax : ShortReal from Standard)
355 ---Purpose: call_togl_graduatedtrihedron_minmaxvalues
358 ----------------------------------
359 -- Category: Immediate mode methods
360 ----------------------------------
362 SetImmediateModeDrawToFront (me : mutable;
363 theCView : CView from Graphic3d;
364 theDrawToFrontBuffer : Boolean from Standard)
365 returns Boolean from Standard
367 ---Purpose: @param theDrawToFrontBuffer Advanced option to modify rendering mode:
368 -- 1. TRUE. Drawing immediate mode structures directly to the front buffer over the scene image.
369 -- Fast, so preferred for interactive work (used by default).
370 -- However these extra drawings will be missed in image dump since it is performed from back buffer.
371 -- Notice that since no pre-buffering used the V-Sync will be ignored and rendering could be seen
372 -- in run-time (in case of slow hardware) and/or tearing may appear.
373 -- So this is strongly recommended to draw only simple (fast) structures.
374 -- 2. FALSE. Drawing immediate mode structures to the back buffer.
375 -- The complete scene is redrawn first, so this mode is slower if scene contains complex data and/or V-Sync is turned on.
376 -- But it works in any case and is especially useful for view dump because the dump image is read from the back buffer.
377 -- @return previous mode.
379 DisplayImmediateStructure ( me : mutable;
380 theCView : CView from Graphic3d;
381 theCStructure : CStructure from Graphic3d )
383 ---Purpose: Display structure in immediate mode on top of general presentation
385 EraseImmediateStructure ( me : mutable;
386 theCView : CView from Graphic3d;
387 theCStructure : CStructure from Graphic3d )
389 ---Purpose: Erases immediate structure
391 -------------------------------
392 -- Category: Layer mode methods
393 -------------------------------
395 Layer ( me : mutable;
396 ACLayer : in out CLayer2d from Aspect )
398 ---Purpose: call_togl_layer2d
400 RemoveLayer ( me : mutable;
401 ACLayer : CLayer2d from Aspect )
403 ---Purpose: call_togl_removelayer2d
405 BeginLayer ( me : mutable;
406 ACLayer : CLayer2d from Aspect )
408 ---Purpose: call_togl_begin_layer2d
410 BeginPolygon2d ( me : mutable )
412 ---Purpose: call_togl_begin_polygon2d
414 BeginPolyline2d ( me : mutable )
416 ---Purpose: call_togl_begin_polyline2d
418 ClearLayer ( me : mutable;
419 ACLayer : CLayer2d from Aspect )
421 ---Purpose: call_togl_clear_layer2d
424 X : ShortReal from Standard;
425 Y : ShortReal from Standard )
427 ---Purpose: call_togl_draw2d
430 X : ShortReal from Standard;
431 Y : ShortReal from Standard )
433 ---Purpose: call_togl_edge2d
435 EndLayer ( me : mutable )
437 ---Purpose: call_togl_end_layer2d
439 EndPolygon2d ( me : mutable )
441 ---Purpose: call_togl_end_polygon2d
443 EndPolyline2d ( me : mutable )
445 ---Purpose: call_togl_end_polyline2d
448 X : ShortReal from Standard;
449 Y : ShortReal from Standard )
451 ---Purpose: call_togl_move2d
453 Rectangle ( me : mutable;
454 X, Y : ShortReal from Standard;
455 Width, Height : ShortReal from Standard )
457 ---Purpose: call_togl_rectangle2d
459 SetColor ( me : mutable;
460 R : ShortReal from Standard;
461 G : ShortReal from Standard;
462 B : ShortReal from Standard )
464 ---Purpose: call_togl_set_color
466 SetTransparency ( me : mutable;
467 ATransparency : ShortReal from Standard )
469 ---Purpose: call_togl_set_transparency
471 UnsetTransparency ( me : mutable )
473 ---Purpose: call_togl_unset_transparency
475 SetLineAttributes ( me : mutable;
476 Type : Integer from Standard;
477 Width : ShortReal from Standard )
479 ---Purpose: call_togl_set_line_attributes
482 SetTextAttributes ( me : mutable;
483 Font : CString from Standard;
484 Type : Integer from Standard;
485 R : ShortReal from Standard;
486 G : ShortReal from Standard;
487 B : ShortReal from Standard )
489 ---Purpose: Set text attributes for under-/overlayer.
490 -- <Font> argument defines the name of the font to be used,
491 -- <Type> argument defines the display type of the text,
492 -- <R> <G> <B> values define the color of decal or subtitle background.
493 -- To set the color of the text you can use the SetColor method.
496 AText : CString from Standard;
497 X, Y : ShortReal from Standard;
498 AHeight : ShortReal from Standard )
500 ---Purpose: call_togl_text2d
501 -- If AHeight < 0 default text height is used by driver (DefaultTextHeight method)
503 DefaultTextHeight( me )
504 returns ShortReal from Standard
509 AText : CString from Standard;
510 AHeight : ShortReal from Standard;
511 AWidth : in out ShortReal from Standard;
512 AnAscent : in out ShortReal from Standard;
513 ADescent : in out ShortReal from Standard )
515 ---Purpose: call_togl_textsize2d
517 SetBackFacingModel ( me : mutable;
518 aView : CView from Graphic3d )
520 ---Purpose: call_togl_backfacing
522 SetDepthTestEnabled( me; view : CView from Graphic3d;
523 isEnabled : Boolean from Standard )
525 ---Purpose: call_togl_depthtest
527 IsDepthTestEnabled( me; view : CView from Graphic3d )
528 returns Boolean from Standard is deferred;
529 ---Purpose: call_togl_isdepthtest
532 view : CView from Graphic3d;
534 width, height : Integer;
537 ---Purpose: Reads depths of shown pixels of the given
538 -- rectangle (glReadPixels with GL_DEPTH_COMPONENT)
540 FBOCreate( me : mutable;
541 view : CView from Graphic3d;
542 width, height : Integer from Standard )
543 returns PtrFrameBuffer from Graphic3d
545 ---Purpose: Generate offscreen FBO in the graphic library.
546 -- If not supported on hardware returns NULL.
548 FBORelease( me : mutable;
549 view : CView from Graphic3d;
550 fboPtr : in out PtrFrameBuffer from Graphic3d )
552 ---Purpose: Remove offscreen FBO from the graphic library
554 FBOGetDimensions( me : mutable;
555 view : CView from Graphic3d;
556 fboPtr : PtrFrameBuffer from Graphic3d;
557 width, height : out Integer from Standard;
558 widthMax, heightMax : out Integer from Standard )
560 ---Purpose: Read offscreen FBO configuration.
562 FBOChangeViewport( me : mutable;
563 view : CView from Graphic3d;
564 fboPtr : in out PtrFrameBuffer from Graphic3d;
565 width, height : Integer from Standard )
567 ---Purpose: Change offscreen FBO viewport.
569 BufferDump( me : mutable;
570 theCView : CView from Graphic3d;
571 theImage : in out PixMap from Image;
572 theBufferType : BufferType from Graphic3d )
573 returns Boolean from Standard
575 ---Purpose: Dump active rendering buffer into specified memory buffer.
577 SetGLLightEnabled( me; view : CView from Graphic3d;
578 isEnabled : Boolean from Standard )
580 ---Purpose: call_togl_gllight
582 IsGLLightEnabled( me; view : CView from Graphic3d )
583 returns Boolean from Standard is deferred;
584 ---Purpose: call_togl_isgllight
587 ACView : CView from Graphic3d;
588 ACUnderLayer : CLayer2d from Aspect;
589 ACOverLayer : CLayer2d from Aspect;
590 hPrnDC : Handle from Aspect;
591 showBackground : Boolean;
593 printAlgorithm : PrintAlgo from Aspect = Aspect_PA_STRETCH;
594 theScaleFactor : Real from Standard = 1.0 )
595 returns Boolean from Standard is deferred;
597 ---Purpose: print the contents of all layers of the view to the printer.
598 -- <hPrnDC> : Pass the PrinterDeviceContext (HDC),
599 -- <showBackground> : When set to FALSE then print the view without background color
600 -- (background is white)
601 -- else set to TRUE for printing with current background color.
602 -- <filename>: If != NULL, then the view will be printed to a file.
603 -- <printAlgorithm>: Select print algorithm: stretch, tile.
604 -- <theScaleFactor>: Scaling coefficient, used internally to scale the
605 -- printings accordingly to the scale factor selected in the printer
606 -- properties dialog.
607 -- Returns Standard_True if the data is passed to the printer, otherwise
608 -- Standard_False if the print operation failed due to the printer errors,
609 -- or insufficient system memory available.
610 ---Warning: Works only under Windows.
613 theFileName : CString from Standard;
614 theFormat : ExportFormat from Graphic3d;
615 theSortType : SortType from Graphic3d;
616 theWidth, theHeight : Integer from Standard;
617 theView : CView from Graphic3d;
618 theLayerUnder : CLayer2d from Aspect;
619 theLayerOver : CLayer2d from Aspect;
620 thePrecision : Real from Standard = 0.005;
621 theProgressBarFunc : Address from Standard = NULL;
622 theProgressObject : Address from Standard = NULL )
623 returns Boolean from Standard
626 -- Export scene into the one of the Vector graphics formats (SVG, PS, PDF...).
627 -- In contrast to Bitmaps, Vector graphics is scalable (so you may got quality benefits on printing to laser printer).
628 -- Notice however that results may differ a lot and do not contain some elements.
630 InvalidateBVHData( me : mutable;
631 theCView : out CView from Graphic3d;
632 theLayerId : Integer from Standard )
635 -- Marks BVH tree and the set of BVH primitives of correspondent priority list with id theLayerId as outdated.
637 AddZLayer( me : mutable;
638 theCView : CView from Graphic3d;
639 theLayerId : Integer from Standard )
641 ---Purpose: Add a new top-level z layer with ID <theLayerId> for
642 -- the view. Z layers allow drawing structures in higher layers
643 -- in foreground of structures in lower layers. To add a structure
644 -- to desired layer on display it is necessary to set the layer
645 -- ID for the structure.
647 RemoveZLayer( me : mutable;
648 theCView : CView from Graphic3d;
649 theLayerId : Integer from Standard )
651 ---Purpose: Remove Z layer from the specified view. All structures
652 -- displayed at the moment in layer will be displayed in default layer
653 -- ( the bottom-level z layer ). To unset layer ID from associated
654 -- structures use method UnsetZLayer (...).
656 UnsetZLayer( me : mutable;
657 theLayerId : Integer from Standard )
659 ---Purpose: Unset Z layer ID for all structures. The structure
660 -- indexes will be set to default layer ( the bottom-level z layer
663 ChangeZLayer( me : mutable;
664 theCStructure : CStructure from Graphic3d;
665 theLayerId : Integer from Standard )
667 ---Purpose: Change Z layer of a structure. The new z layer ID will
668 -- be used to define the associated layer for structure on display.
670 ChangeZLayer( me : mutable;
671 theCStructure : CStructure from Graphic3d;
672 theCView : CView from Graphic3d;
673 theNewLayerId : Integer from Standard )
675 ---Purpose: Change Z layer of a structure already presented in view.
678 theCStructure : CStructure from Graphic3d )
679 returns Integer from Standard is deferred;
680 ---Purpose: Get Z layer ID of structure. If the structure doesn't
681 -- exists in graphic driver, the method returns -1.
683 SetZLayerSettings( me : mutable;
684 theCView : CView from Graphic3d;
685 theLayerId : Integer from Standard;
686 theSettings : ZLayerSettings from Graphic3d)
688 ---Purpose: Sets the settings for a single Z layer of specified view.
690 ChangePriority( me : mutable;
691 theCStructure : CStructure from Graphic3d;
692 theCView : CView from Graphic3d;
693 theNewPriority : Integer from Standard )
695 ---Purpose: Changes the priority of a structure within its Z layer
696 -- in the specified view.
698 -----------------------------
699 -- Category: Internal methods
700 -----------------------------
703 AComment : CString from Standard;
704 AValue : Boolean from Standard );
707 ACLight : CLight from Graphic3d;
708 AField : Integer from Standard );
711 ACPick : CPick from Graphic3d;
712 AField : Integer from Standard );
714 PrintCStructure ( me;
715 ACStructure : CStructure from Graphic3d;
716 AField : Integer from Standard );
719 ACView : CView from Graphic3d;
720 AField : Integer from Standard );
723 AFunc : CString from Standard );
726 AComment : CString from Standard;
727 AValue : Integer from Standard );
730 AFunc : CString from Standard;
731 AResult : Integer from Standard );
734 AComment : CString from Standard;
735 AValue : ShortReal from Standard );
738 AComment : CString from Standard;
739 AMatrix : Array2OfReal from TColStd )
740 raises TransformError from Graphic3d;
743 AComment : CString from Standard;
744 AString : CString from Standard );
746 SetTrace ( me : mutable;
747 ALevel : Integer from Standard )
751 returns Integer from Standard
754 GetDisplayConnection (me)
755 returns DisplayConnection_Handle from Aspect;
756 ---C++: return const &
758 ---Purpose: returns Handle to display connection
761 returns Boolean from Standard;
762 -- Purpose: @return Standard_True in cases when the last view has been removed but some objects still present.
764 ResetDeviceLostFlag (me: mutable);
765 -- Purpose: Resets DeviceLostFlag to default (Standard_False) state.
769 MyTraceLevel : Integer from Standard is protected;
770 myDisplayConnection: DisplayConnection_Handle from Aspect is protected;
771 myDeviceLostFlag : Boolean from Standard is protected;
773 end GraphicDriver from Graphic3d;