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 -- (currently only OpenGl driver is used).
31 SharedLibrary from OSD,
33 Array1OfInteger from TColStd,
34 Array1OfReal from TColStd,
35 Array2OfReal from TColStd,
37 AsciiString from TCollection,
38 ExtendedString from TCollection,
40 NameOfColor from Quantity,
43 PlaneAngle from Quantity,
47 Array1OfEdge from Aspect,
49 TypeOfTriedronEcho from Aspect,
50 TypeOfTriedronPosition from Aspect,
53 PrintAlgo from Aspect,
54 DisplayConnection_Handle from Aspect,
56 ZLayerSettings from Graphic3d,
58 AspectLine3d from Graphic3d,
59 AspectMarker3d from Graphic3d,
60 AspectText3d from Graphic3d,
61 AspectFillArea3d from Graphic3d,
62 HorizontalTextAlignment from Graphic3d,
63 CBitFields20 from Graphic3d,
65 CLight from Graphic3d,
67 CPlane from Graphic3d,
68 CStructure from Graphic3d,
69 CStructure_Handle from Graphic3d,
71 BufferType from Graphic3d,
72 Structure from Graphic3d,
73 StructureManager from Graphic3d,
74 TextPath from Graphic3d,
75 TypeOfComposition from Graphic3d,
76 TypeOfPrimitive from Graphic3d,
77 Vector from Graphic3d,
78 Array1OfVertex from Graphic3d,
79 Array2OfVertex from Graphic3d,
80 Vertex from Graphic3d,
81 VerticalTextAlignment from Graphic3d,
82 PtrFrameBuffer from Graphic3d,
83 HArray1OfByte from TColStd,
84 FillMethod from Aspect,
85 GradientFillMethod from Aspect,
86 ExportFormat from Graphic3d,
87 SortType from Graphic3d,
88 HArray1OfReal from TColStd,
89 CUserDraw from Graphic3d,
90 NListOfHAsciiString from Graphic3d,
92 CGraduatedTrihedron from Graphic3d,
93 ClipPlane from Graphic3d,
98 TransformError from Graphic3d
101 Initialize ( AShrName : CString from Standard )
102 returns mutable GraphicDriver from Graphic3d;
104 ---Purpose: Initialises the Driver
106 -------------------------
107 -- Category: Init methods
108 -------------------------
111 theDisplayConnection: DisplayConnection_Handle from Aspect)
112 returns Boolean from Standard
114 ---Purpose: Starts graphic driver with given connection
118 ---Purpose: call_togl_end
120 ----------------------------
121 -- Category: Inquire methods
122 ----------------------------
124 InquireLightLimit ( me : mutable )
125 returns Integer from Standard
127 ---Purpose: call_togl_inquirelight
129 InquirePlaneLimit ( me : mutable )
130 returns Integer from Standard
132 ---Purpose: call_togl_inquireplane
134 InquireViewLimit ( me : mutable )
135 returns Integer from Standard
137 ---Purpose: call_togl_inquireview
139 -----------------------------------------
140 -- Category: Structure management methods
141 -----------------------------------------
143 DisplayStructure ( me : mutable;
144 theCView : CView from Graphic3d;
145 theCStructure : in out CStructure from Graphic3d;
146 thePriority : Integer from Standard )
148 ---Purpose: call_togl_displaystructure
150 EraseStructure ( me : mutable;
151 theCView : CView from Graphic3d;
152 theCStructure : in out CStructure from Graphic3d )
154 ---Purpose: call_togl_erasestructure
156 RemoveStructure ( me : mutable;
157 theCStructure : in out CStructure_Handle from Graphic3d )
159 ---Purpose: call_togl_removestructure
161 Structure (me : mutable;
162 theManager : StructureManager from Graphic3d)
163 returns CStructure_Handle from Graphic3d
165 ---Purpose: Creates new empty graphic structure
167 ------------------------------------
168 -- Category: Structured mode methods
169 ------------------------------------
171 ActivateView ( me : mutable;
172 ACView : CView from Graphic3d )
174 ---Purpose: call_togl_activateview
176 AntiAliasing ( me : mutable;
177 ACView : CView from Graphic3d;
178 AFlag : Boolean from Standard )
180 ---Purpose: call_togl_antialiasing
182 Background ( me : mutable;
183 ACView : CView from Graphic3d )
185 ---Purpose: call_togl_background
187 GradientBackground ( me : mutable;
188 ACView : CView from Graphic3d;
189 AColor1: Color from Quantity;
190 AColor2: Color from Quantity;
191 FillStyle : GradientFillMethod from Aspect
194 ---Purpose: call_togl_gradient_background
197 BackgroundImage( me : mutable;
198 FileName : CString from Standard;
199 ACView : CView from Graphic3d;
200 FillStyle : FillMethod from Aspect )
203 SetBgImageStyle( me : mutable;
204 ACView : CView from Graphic3d;
205 FillStyle : FillMethod from Aspect )
208 SetBgGradientStyle( me : mutable;
209 ACView : CView from Graphic3d;
210 FillStyle : GradientFillMethod from Aspect )
213 ClipLimit ( me : mutable;
214 ACView : CView from Graphic3d;
215 AWait : Boolean from Standard )
217 ---Purpose: call_togl_cliplimit
219 DeactivateView ( me : mutable;
220 ACView : CView from Graphic3d )
222 ---Purpose: call_togl_deactivateview
224 DepthCueing ( me : mutable;
225 ACView : CView from Graphic3d;
226 AFlag : Boolean from Standard )
228 ---Purpose: call_togl_cliplimit
230 RatioWindow ( me : mutable;
231 ACView : CView from Graphic3d )
233 ---Purpose: call_togl_ratio_window
235 Redraw ( me : mutable;
236 theCView : CView from Graphic3d;
237 theCUnderLayer : CLayer2d from Aspect;
238 theCOverLayer : CLayer2d from Aspect;
241 theWidth : Integer = 0;
242 theHeight : Integer = 0 )
244 ---Purpose: Redraw content of the view
246 RedrawImmediate ( me : mutable;
247 theCView : CView from Graphic3d;
248 theCUnderLayer : CLayer2d from Aspect;
249 theCOverLayer : CLayer2d from Aspect )
251 ---Purpose: Redraw layer of immediate presentations
253 Invalidate ( me : mutable;
254 theCView : CView from Graphic3d )
256 ---Purpose: Invalidates content of the view but does not redraw it
258 RemoveView ( me : mutable;
259 ACView : CView from Graphic3d )
261 ---Purpose: call_togl_removeview
263 SetLight ( me : mutable;
264 ACView : CView from Graphic3d )
266 ---Purpose: call_togl_setlight
268 SetClipPlanes (me : mutable; theCView : CView from Graphic3d) is deferred;
269 ---Purpose: Pass clip planes to the associated graphic driver view.
271 SetCamera (me : mutable; theCView : CView from Graphic3d)
273 ---Purpose: Inform graphic driver if camera assigned to view changes.
275 SetVisualisation ( me : mutable;
276 ACView : CView from Graphic3d )
278 ---Purpose: call_togl_setvisualisation
280 Transparency ( me : mutable;
281 ACView : CView from Graphic3d;
282 AFlag : Boolean from Standard )
284 ---Purpose: call_togl_transparency
287 ACView : in out CView from Graphic3d )
288 returns Boolean from Standard
290 ---Purpose: call_togl_view
292 Environment ( me : mutable;
293 ACView : CView from Graphic3d )
297 ----------------------------------------
298 ---Category: Methods to create Triangle
299 -- for Purpose : see Graphic3d_Group.cdl
300 ----------------------------------------
302 EnableVBO( me : mutable;
303 status : Boolean from Standard )
305 ---Purpose: enables/disables usage of OpenGL vertex buffer arrays while drawing primitiev arrays
308 theFreeBytes : out Size from Standard;
309 theInfo : out AsciiString from TCollection) returns Boolean from Standard is deferred;
310 ---Purpose: Returns information about GPU memory usage.
312 ----------------------------------------
313 ---Category: Methods to create Triedron
314 -- for Purpose : see Graphic3d_Group.cdl
315 ----------------------------------------
317 ZBufferTriedronSetup ( me : mutable;
318 XColor : NameOfColor from Quantity = Quantity_NOC_RED;
319 YColor : NameOfColor from Quantity = Quantity_NOC_GREEN;
320 ZColor : NameOfColor from Quantity = Quantity_NOC_BLUE1;
321 SizeRatio : Real from Standard = 0.8;
322 AxisDiametr : Real from Standard = 0.05;
323 NbFacettes : Integer from Standard = 12)
325 ---Purpose: call_togl_ztriedron_setup
327 TriedronDisplay ( me : mutable;
328 ACView : CView from Graphic3d;
329 APosition : TypeOfTriedronPosition from Aspect = Aspect_TOTP_CENTER;
330 AColor : NameOfColor from Quantity = Quantity_NOC_WHITE ;
331 AScale : Real from Standard = 0.02;
332 AsWireframe : Boolean from Standard = Standard_True )
334 ---Purpose: call_togl_triedron_display
337 TriedronErase ( me : mutable;
338 ACView : CView from Graphic3d)
340 ---Purpose: call_togl_triedron_erase
343 TriedronEcho ( me : mutable;
344 ACView : CView from Graphic3d;
345 AType : TypeOfTriedronEcho from Aspect = Aspect_TOTE_NONE )
347 ---Purpose: call_togl_triedron_echo
349 ---------------------------------
350 ---Category: Graduated trihedron
351 ---------------------------------
353 GraduatedTrihedronDisplay(me : mutable;
354 view : CView from Graphic3d;
355 cubic : CGraduatedTrihedron from Graphic3d)
356 ---Purpose: call_togl_graduatedtrihedron_display
359 GraduatedTrihedronErase(me : mutable;
360 view : CView from Graphic3d)
361 ---Purpose: call_togl_graduatedtrihedron_erase
364 GraduatedTrihedronMinMaxValues(me : mutable;
365 xmin : ShortReal from Standard;
366 ymin : ShortReal from Standard;
367 zmin : ShortReal from Standard;
368 xmax : ShortReal from Standard;
369 ymax : ShortReal from Standard;
370 zmax : ShortReal from Standard)
371 ---Purpose: call_togl_graduatedtrihedron_minmaxvalues
374 ----------------------------------
375 -- Category: Immediate mode methods
376 ----------------------------------
378 SetImmediateModeDrawToFront (me : mutable;
379 theCView : CView from Graphic3d;
380 theDrawToFrontBuffer : Boolean from Standard)
381 returns Boolean from Standard
383 ---Purpose: @param theDrawToFrontBuffer Advanced option to modify rendering mode:
384 -- 1. TRUE. Drawing immediate mode structures directly to the front buffer over the scene image.
385 -- Fast, so preferred for interactive work (used by default).
386 -- However these extra drawings will be missed in image dump since it is performed from back buffer.
387 -- Notice that since no pre-buffering used the V-Sync will be ignored and rendering could be seen
388 -- in run-time (in case of slow hardware) and/or tearing may appear.
389 -- So this is strongly recommended to draw only simple (fast) structures.
390 -- 2. FALSE. Drawing immediate mode structures to the back buffer.
391 -- The complete scene is redrawn first, so this mode is slower if scene contains complex data and/or V-Sync is turned on.
392 -- But it works in any case and is especially useful for view dump because the dump image is read from the back buffer.
393 -- @return previous mode.
395 DisplayImmediateStructure ( me : mutable;
396 theCView : CView from Graphic3d;
397 theCStructure : CStructure from Graphic3d )
399 ---Purpose: Display structure in immediate mode on top of general presentation
401 EraseImmediateStructure ( me : mutable;
402 theCView : CView from Graphic3d;
403 theCStructure : CStructure from Graphic3d )
405 ---Purpose: Erases immediate structure
407 -------------------------------
408 -- Category: Layer mode methods
409 -------------------------------
411 Layer ( me : mutable;
412 ACLayer : in out CLayer2d from Aspect )
414 ---Purpose: call_togl_layer2d
416 RemoveLayer ( me : mutable;
417 ACLayer : CLayer2d from Aspect )
419 ---Purpose: call_togl_removelayer2d
421 BeginLayer ( me : mutable;
422 ACLayer : CLayer2d from Aspect )
424 ---Purpose: call_togl_begin_layer2d
426 BeginPolygon2d ( me : mutable )
428 ---Purpose: call_togl_begin_polygon2d
430 BeginPolyline2d ( me : mutable )
432 ---Purpose: call_togl_begin_polyline2d
434 ClearLayer ( me : mutable;
435 ACLayer : CLayer2d from Aspect )
437 ---Purpose: call_togl_clear_layer2d
440 X : ShortReal from Standard;
441 Y : ShortReal from Standard )
443 ---Purpose: call_togl_draw2d
446 X : ShortReal from Standard;
447 Y : ShortReal from Standard )
449 ---Purpose: call_togl_edge2d
451 EndLayer ( me : mutable )
453 ---Purpose: call_togl_end_layer2d
455 EndPolygon2d ( me : mutable )
457 ---Purpose: call_togl_end_polygon2d
459 EndPolyline2d ( me : mutable )
461 ---Purpose: call_togl_end_polyline2d
464 X : ShortReal from Standard;
465 Y : ShortReal from Standard )
467 ---Purpose: call_togl_move2d
469 Rectangle ( me : mutable;
470 X, Y : ShortReal from Standard;
471 Width, Height : ShortReal from Standard )
473 ---Purpose: call_togl_rectangle2d
475 SetColor ( me : mutable;
476 R : ShortReal from Standard;
477 G : ShortReal from Standard;
478 B : ShortReal from Standard )
480 ---Purpose: call_togl_set_color
482 SetTransparency ( me : mutable;
483 ATransparency : ShortReal from Standard )
485 ---Purpose: call_togl_set_transparency
487 UnsetTransparency ( me : mutable )
489 ---Purpose: call_togl_unset_transparency
491 SetLineAttributes ( me : mutable;
492 Type : Integer from Standard;
493 Width : ShortReal from Standard )
495 ---Purpose: call_togl_set_line_attributes
498 SetTextAttributes ( me : mutable;
499 Font : CString from Standard;
500 Type : Integer from Standard;
501 R : ShortReal from Standard;
502 G : ShortReal from Standard;
503 B : ShortReal from Standard )
505 ---Purpose: Set text attributes for under-/overlayer.
506 -- <Font> argument defines the name of the font to be used,
507 -- <Type> argument defines the display type of the text,
508 -- <R> <G> <B> values define the color of decal or subtitle background.
509 -- To set the color of the text you can use the SetColor method.
512 AText : CString from Standard;
513 X, Y : ShortReal from Standard;
514 AHeight : ShortReal from Standard )
516 ---Purpose: call_togl_text2d
517 -- If AHeight < 0 default text height is used by driver (DefaultTextHeight method)
519 DefaultTextHeight( me )
520 returns ShortReal from Standard
525 AText : CString from Standard;
526 AHeight : ShortReal from Standard;
527 AWidth : in out ShortReal from Standard;
528 AnAscent : in out ShortReal from Standard;
529 ADescent : in out ShortReal from Standard )
531 ---Purpose: call_togl_textsize2d
533 SetBackFacingModel ( me : mutable;
534 aView : CView from Graphic3d )
536 ---Purpose: call_togl_backfacing
538 SetDepthTestEnabled( me; view : CView from Graphic3d;
539 isEnabled : Boolean from Standard )
541 ---Purpose: call_togl_depthtest
543 IsDepthTestEnabled( me; view : CView from Graphic3d )
544 returns Boolean from Standard is deferred;
545 ---Purpose: call_togl_isdepthtest
548 view : CView from Graphic3d;
550 width, height : Integer;
553 ---Purpose: Reads depths of shown pixels of the given
554 -- rectangle (glReadPixels with GL_DEPTH_COMPONENT)
556 FBOCreate( me : mutable;
557 view : CView from Graphic3d;
558 width, height : Integer from Standard )
559 returns PtrFrameBuffer from Graphic3d
561 ---Purpose: Generate offscreen FBO in the graphic library.
562 -- If not supported on hardware returns NULL.
564 FBORelease( me : mutable;
565 view : CView from Graphic3d;
566 fboPtr : in out PtrFrameBuffer from Graphic3d )
568 ---Purpose: Remove offscreen FBO from the graphic library
570 FBOGetDimensions( me : mutable;
571 view : CView from Graphic3d;
572 fboPtr : PtrFrameBuffer from Graphic3d;
573 width, height : out Integer from Standard;
574 widthMax, heightMax : out Integer from Standard )
576 ---Purpose: Read offscreen FBO configuration.
578 FBOChangeViewport( me : mutable;
579 view : CView from Graphic3d;
580 fboPtr : in out PtrFrameBuffer from Graphic3d;
581 width, height : Integer from Standard )
583 ---Purpose: Change offscreen FBO viewport.
585 BufferDump( me : mutable;
586 theCView : CView from Graphic3d;
587 theImage : in out PixMap from Image;
588 theBufferType : BufferType from Graphic3d )
589 returns Boolean from Standard
591 ---Purpose: Dump active rendering buffer into specified memory buffer.
593 SetGLLightEnabled( me; view : CView from Graphic3d;
594 isEnabled : Boolean from Standard )
596 ---Purpose: call_togl_gllight
598 IsGLLightEnabled( me; view : CView from Graphic3d )
599 returns Boolean from Standard is deferred;
600 ---Purpose: call_togl_isgllight
603 ACView : CView from Graphic3d;
604 ACUnderLayer : CLayer2d from Aspect;
605 ACOverLayer : CLayer2d from Aspect;
606 hPrnDC : Handle from Aspect;
607 showBackground : Boolean;
609 printAlgorithm : PrintAlgo from Aspect = Aspect_PA_STRETCH;
610 theScaleFactor : Real from Standard = 1.0 )
611 returns Boolean from Standard is deferred;
613 ---Purpose: print the contents of all layers of the view to the printer.
614 -- <hPrnDC> : Pass the PrinterDeviceContext (HDC),
615 -- <showBackground> : When set to FALSE then print the view without background color
616 -- (background is white)
617 -- else set to TRUE for printing with current background color.
618 -- <filename>: If != NULL, then the view will be printed to a file.
619 -- <printAlgorithm>: Select print algorithm: stretch, tile.
620 -- <theScaleFactor>: Scaling coefficient, used internally to scale the
621 -- printings accordingly to the scale factor selected in the printer
622 -- properties dialog.
623 -- Returns Standard_True if the data is passed to the printer, otherwise
624 -- Standard_False if the print operation failed due to the printer errors,
625 -- or insufficient system memory available.
626 ---Warning: Works only under Windows.
629 theFileName : CString from Standard;
630 theFormat : ExportFormat from Graphic3d;
631 theSortType : SortType from Graphic3d;
632 theWidth, theHeight : Integer from Standard;
633 theView : CView from Graphic3d;
634 theLayerUnder : CLayer2d from Aspect;
635 theLayerOver : CLayer2d from Aspect;
636 thePrecision : Real from Standard = 0.005;
637 theProgressBarFunc : Address from Standard = NULL;
638 theProgressObject : Address from Standard = NULL )
639 returns Boolean from Standard
642 -- Export scene into the one of the Vector graphics formats (SVG, PS, PDF...).
643 -- In contrast to Bitmaps, Vector graphics is scalable (so you may got quality benefits on printing to laser printer).
644 -- Notice however that results may differ a lot and do not contain some elements.
646 AddZLayer( me : mutable;
647 theCView : CView from Graphic3d;
648 theLayerId : Integer from Standard )
650 ---Purpose: Add a new top-level z layer with ID <theLayerId> for
651 -- the view. Z layers allow drawing structures in higher layers
652 -- in foreground of structures in lower layers. To add a structure
653 -- to desired layer on display it is necessary to set the layer
654 -- ID for the structure.
656 RemoveZLayer( me : mutable;
657 theCView : CView from Graphic3d;
658 theLayerId : Integer from Standard )
660 ---Purpose: Remove Z layer from the specified view. All structures
661 -- displayed at the moment in layer will be displayed in default layer
662 -- ( the bottom-level z layer ). To unset layer ID from associated
663 -- structures use method UnsetZLayer (...).
665 UnsetZLayer( me : mutable;
666 theLayerId : Integer from Standard )
668 ---Purpose: Unset Z layer ID for all structures. The structure
669 -- indexes will be set to default layer ( the bottom-level z layer
672 ChangeZLayer( me : mutable;
673 theCStructure : CStructure from Graphic3d;
674 theLayerId : Integer from Standard )
676 ---Purpose: Change Z layer of a structure. The new z layer ID will
677 -- be used to define the associated layer for structure on display.
679 ChangeZLayer( me : mutable;
680 theCStructure : CStructure from Graphic3d;
681 theCView : CView from Graphic3d;
682 theNewLayerId : Integer from Standard )
684 ---Purpose: Change Z layer of a structure already presented in view.
687 theCStructure : CStructure from Graphic3d )
688 returns Integer from Standard is deferred;
689 ---Purpose: Get Z layer ID of structure. If the structure doesn't
690 -- exists in graphic driver, the method returns -1.
692 SetZLayerSettings( me : mutable;
693 theCView : CView from Graphic3d;
694 theLayerId : Integer from Standard;
695 theSettings : ZLayerSettings from Graphic3d)
697 ---Purpose: Sets the settings for a single Z layer of specified view.
699 -----------------------------
700 -- Category: Internal methods
701 -----------------------------
704 AComment : CString from Standard;
705 AValue : Boolean from Standard );
708 ACLight : CLight from Graphic3d;
709 AField : Integer from Standard );
712 ACPick : CPick from Graphic3d;
713 AField : Integer from Standard );
715 PrintCStructure ( me;
716 ACStructure : CStructure from Graphic3d;
717 AField : Integer from Standard );
720 ACView : CView from Graphic3d;
721 AField : Integer from Standard );
724 AFunc : CString from Standard );
727 AComment : CString from Standard;
728 AValue : Integer from Standard );
731 AFunc : CString from Standard;
732 AResult : Integer from Standard );
735 AComment : CString from Standard;
736 AValue : ShortReal from Standard );
739 AComment : CString from Standard;
740 AMatrix : Array2OfReal from TColStd )
741 raises TransformError from Graphic3d;
744 AComment : CString from Standard;
745 AString : CString from Standard );
747 SetTrace ( me : mutable;
748 ALevel : Integer from Standard )
752 returns Integer from Standard
755 --ListOfAvalableFontNames( me;
756 -- lst: out NListOfHAsciiString from Graphic3d )
757 -- returns Boolean from Standard
759 -- Purpose: Initialize list of names of avalable system fonts
760 -- returns Standard_False if fails
761 -- ABD Integration support of system fonts (using FTGL and FreeType)
763 GetDisplayConnection (me)
764 returns DisplayConnection_Handle from Aspect;
765 ---C++: return const &
767 ---Purpose: returns Handle to display connection
770 returns Boolean from Standard;
771 -- Purpose: @return Standard_True in cases when the last view has been removed but some objects still present.
773 ResetDeviceLostFlag (me: mutable);
774 -- Purpose: Resets DeviceLostFlag to default (Standard_False) state.
778 MyTraceLevel : Integer from Standard is protected;
779 MySharedLibrary : SharedLibrary from OSD is protected;
780 myDisplayConnection: DisplayConnection_Handle from Aspect is protected;
781 myDeviceLostFlag : Boolean from Standard is protected;
783 end GraphicDriver from Graphic3d;