home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / QuickTime VR / Windows / Interfaces / QD3DView.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-05-03  |  17.6 KB  |  566 lines  |  [TEXT/MPS ]
  1. /******************************************************************************
  2.  **                                                                             **
  3.  **     Module:        QD3DView.h                                                 **
  4.  **                                                                             **
  5.  **                                                                             **
  6.  **     Purpose:     View types and routines                                     **
  7.  **                                                                             **
  8.  **                                                                             **
  9.  **                                                                             **
  10.  **     Copyright (C) 1992-1996 Apple Computer, Inc.  All rights reserved.     **
  11.  **                                                                             **
  12.  **                                                                             **
  13.  *****************************************************************************/
  14. #ifndef QD3DView_h
  15. #define QD3DView_h
  16.  
  17. #if PRAGMA_ONCE
  18.     #pragma once
  19. #endif
  20.  
  21. #include "QD3DStyle.h"
  22. #include "QD3DSet.h"
  23.  
  24. #if defined(THINK_C) || defined(__SC__)
  25.     #pragma options(!pack_enums, !align_arrays)
  26.     #pragma SC options align=power
  27. #elif defined(__MWERKS__)
  28.     #pragma enumsalwaysint on
  29.     #pragma align_array_members off
  30.     #pragma options align=native
  31. #elif defined(__PPCC__)
  32.     #pragma options align=power
  33. #elif defined(__xlc) || defined(__xlC) || defined(__xlC__) || defined(__XLC121__)
  34.     #pragma options enum=int
  35. #endif
  36.  
  37. #ifdef __cplusplus
  38. extern "C" {
  39. #endif    /* __cplusplus */
  40.  
  41.  
  42. /******************************************************************************
  43.  **                                                                             **
  44.  **                        View Type Definitions                                 **
  45.  **                                                                             **
  46.  *****************************************************************************/
  47.  
  48. typedef enum TQ3ViewStatus {
  49.     kQ3ViewStatusDone,
  50.     kQ3ViewStatusRetraverse,
  51.     kQ3ViewStatusError,
  52.     kQ3ViewStatusCancelled
  53. } TQ3ViewStatus;
  54.  
  55. #if defined(ESCHER_VER_15) && ESCHER_VER_15
  56.  
  57. typedef struct TQ3RendererCachePrivate *TQ3RendererCache;
  58.  
  59. #endif /* ESCHER_VER_15 */
  60.  
  61. /******************************************************************************
  62.  **                                                                             **
  63.  **                        Default Attribute Set                                 **
  64.  **                                                                             **
  65.  *****************************************************************************/
  66.  
  67. #define kQ3ViewDefaultAmbientCoefficient    1.0
  68. #define kQ3ViewDefaultDiffuseColor            0.5, 0.5, 0.5
  69. #define kQ3ViewDefaultSpecularColor            0.5, 0.5, 0.5
  70. #define kQ3ViewDefaultSpecularControl        4.0
  71. #define kQ3ViewDefaultTransparency            1.0, 1.0, 1.0
  72. #define kQ3ViewDefaultHighlightColor        1.0, 0.0, 0.0
  73.  
  74. #define kQ3ViewDefaultSubdivisionMethod        kQ3SubdivisionMethodScreenSpace
  75. #define kQ3ViewDefaultSubdivisionC1            10.0
  76. #define kQ3ViewDefaultSubdivisionC2            10.0
  77.  
  78.  
  79. /******************************************************************************
  80.  **                                                                             **
  81.  **                            View Routines                                     **
  82.  **                                                                             **
  83.  *****************************************************************************/
  84.  
  85. QD3D_EXPORT TQ3ViewObject Q3View_New(
  86.     void);
  87.  
  88. QD3D_EXPORT TQ3Status Q3View_Cancel(
  89.     TQ3ViewObject        view);
  90.  
  91. #if defined(ESCHER_VER_15) && ESCHER_VER_15
  92.  
  93. QD3D_EXPORT TQ3ObjectType Q3View_GetType(
  94.     TQ3ViewObject        view);
  95.     
  96.     
  97. #endif  /*  ESCHER_VER_15  */
  98.  
  99. /******************************************************************************
  100.  **                                                                             **
  101.  **                        View Rendering routines                                 **
  102.  **                                                                             **
  103.  *****************************************************************************/
  104.  
  105. QD3D_EXPORT TQ3Status Q3View_SetRendererByType(
  106.     TQ3ViewObject         view,
  107.     TQ3ObjectType         type);
  108.     
  109. QD3D_EXPORT TQ3Status Q3View_SetRenderer(
  110.     TQ3ViewObject         view,
  111.     TQ3RendererObject    renderer);
  112.  
  113. QD3D_EXPORT TQ3Status Q3View_GetRenderer(
  114.     TQ3ViewObject        view,
  115.     TQ3RendererObject    *renderer);
  116.     
  117. QD3D_EXPORT TQ3Status Q3View_StartRendering(
  118.     TQ3ViewObject         view);
  119.     
  120. QD3D_EXPORT TQ3ViewStatus Q3View_EndRendering(
  121.     TQ3ViewObject         view);
  122.     
  123. QD3D_EXPORT TQ3Status Q3View_Flush(
  124.     TQ3ViewObject        view);
  125.     
  126. QD3D_EXPORT TQ3Status Q3View_Sync(
  127.     TQ3ViewObject        view);
  128.  
  129. #if defined(ESCHER_VER_15) && ESCHER_VER_15
  130.  
  131. /******************************************************************************
  132.  **                                                                             **
  133.  **                        View Cache Rendering routines                         **
  134.  **                                                                             **
  135.  *****************************************************************************/
  136.  
  137. /*
  138.     Q3RendererCache_New
  139.     
  140.     Create a new, empty rendering cache
  141. */
  142. QD3D_EXPORT TQ3RendererCache Q3RendererCache_New(
  143.     void);
  144.  
  145. /*
  146.     Q3RendererCache_Invalidate
  147.     
  148.     Deletes any cached data and forces re-traversal in the
  149.     rendering loop. (see comment below for rendering loop example)
  150. */
  151. QD3D_EXPORT TQ3Status Q3RendererCache_Invalidate(
  152.     TQ3RendererCache        rendererCache);
  153.  
  154. /*
  155.     Q3RendererCache_Delete
  156.     
  157.     Delete a rendering cache.
  158. */
  159. QD3D_EXPORT TQ3Status Q3RendererCache_Delete(
  160.     TQ3RendererCache        rendererCache);
  161.  
  162. /*
  163.     Q3View_StartRendererCache
  164.     Q3View_EndRendererCache
  165.     
  166.     Called between Q3View_StartRendering and Q3View_EndRendering.
  167.     
  168.     Q3View_BeginRendererCache
  169.         returns
  170.             kQ3True if the cache requires re-traversal, or
  171.             kQ3False if the cache is valid.
  172.     
  173.     The dependencies of a renderer cache are based on the implementation
  174.     of a particular renderer. 
  175.     
  176.     For example, a Z-Buffered renderer may cache the pixels and Z information
  177.     for a particular scene, which depends on the lights and camera in a scene.
  178.     
  179.     A ray tracer may cache the geometry list, and references to each geometry.
  180.     
  181.     Therefore, coherency in a renderer cache may depend on what you are
  182.     editing in a scene.
  183.     
  184.     You should structure your code as such:
  185.     
  186.     Q3View_StartRendering(view)
  187.     do {
  188.         if (Q3View_StartRendererCache(view, cacheID))
  189.         {
  190.             Q3Group_Submit(largeAuditorium, view);
  191.             Q3View_EndRendererCache(view);
  192.         }
  193.         Q3Group_Submit(peopleMillingAbout, view);
  194.     } while (Q3View_EndRendering(view) == kQ3ViewStatusRetraverse);
  195.     
  196.     The cached information will be regenerated whenever the cache is
  197.     invalidated.
  198. */
  199.  
  200. QD3D_EXPORT TQ3Boolean Q3View_StartRendererCache(
  201.     TQ3ViewObject            view,
  202.     TQ3RendererCache        cacheID);
  203.  
  204. QD3D_EXPORT TQ3Status Q3View_EndRendererCache(
  205.     TQ3ViewObject            view);
  206.  
  207. #endif  /*  ESCHER_VER_15  */
  208.  
  209. /******************************************************************************
  210.  **                                                                             **
  211.  **                        View/Bounds/Pick routines                             **
  212.  **                                                                             **
  213.  *****************************************************************************/
  214.  
  215. QD3D_EXPORT TQ3Status Q3View_StartBoundingBox(
  216.     TQ3ViewObject        view,
  217.     TQ3ComputeBounds    computeBounds);
  218.  
  219. QD3D_EXPORT TQ3ViewStatus Q3View_EndBoundingBox(
  220.     TQ3ViewObject        view,
  221.     TQ3BoundingBox        *result);
  222.  
  223. QD3D_EXPORT TQ3Status Q3View_StartBoundingSphere(
  224.     TQ3ViewObject        view,
  225.     TQ3ComputeBounds    computeBounds);
  226.  
  227. QD3D_EXPORT TQ3ViewStatus Q3View_EndBoundingSphere(
  228.     TQ3ViewObject        view,
  229.     TQ3BoundingSphere    *result);
  230.  
  231. QD3D_EXPORT TQ3Status Q3View_StartPicking(
  232.     TQ3ViewObject        view,
  233.     TQ3PickObject        pick);
  234.  
  235. QD3D_EXPORT TQ3ViewStatus Q3View_EndPicking(
  236.     TQ3ViewObject        view);
  237.  
  238.  
  239. /******************************************************************************
  240.  **                                                                             **
  241.  **                            View/Camera routines                             **
  242.  **                                                                             **
  243.  *****************************************************************************/
  244.  
  245. QD3D_EXPORT TQ3Status Q3View_GetCamera(
  246.     TQ3ViewObject        view,
  247.     TQ3CameraObject        *camera);
  248.  
  249. QD3D_EXPORT TQ3Status Q3View_SetCamera(
  250.     TQ3ViewObject        view,
  251.     TQ3CameraObject        camera);
  252.  
  253. #if defined(ESCHER_VER_15) && ESCHER_VER_15
  254.  
  255. QD3D_EXPORT TQ3Status Q3View_GetCameraTransformState(
  256.     TQ3ViewObject        view,
  257.     TQ3Boolean            *cameraIsTranformed);
  258.  
  259. QD3D_EXPORT TQ3Status Q3View_SetCameraTransformState(
  260.     TQ3ViewObject        view,
  261.     TQ3Boolean            cameraIsTranformed);
  262.  
  263. #endif  /*  ESCHER_VER_15  */
  264.  
  265. /******************************************************************************
  266.  **                                                                             **
  267.  **                            View/Shader routines                             **
  268.  **                                                                             **
  269.  *****************************************************************************/
  270.  
  271. #if defined(ESCHER_VER_15) && ESCHER_VER_15
  272.  
  273. QD3D_EXPORT TQ3Status Q3View_SetBackgroundShader(
  274.     TQ3ViewObject        view,
  275.     TQ3ShaderObject        backgroundShader);
  276.     
  277. QD3D_EXPORT TQ3Status Q3View_GetBackgroundShader(
  278.     TQ3ViewObject        view,
  279.     TQ3ShaderObject        *backgroundShader);
  280.  
  281. #endif  /*  ESCHER_VER_15  */
  282.  
  283.  
  284. /******************************************************************************
  285.  **                                                                             **
  286.  **                            View/Lights routines                             **
  287.  **                                                                             **
  288.  *****************************************************************************/
  289.  
  290. QD3D_EXPORT TQ3Status Q3View_SetLightGroup(
  291.     TQ3ViewObject        view,
  292.     TQ3GroupObject        lightGroup);
  293.  
  294. QD3D_EXPORT TQ3Status Q3View_GetLightGroup(
  295.     TQ3ViewObject        view,
  296.     TQ3GroupObject        *lightGroup);
  297.  
  298. #if defined(ESCHER_VER_15) && ESCHER_VER_15
  299.  
  300. QD3D_EXPORT TQ3Status Q3View_GetLightTransformState(
  301.     TQ3ViewObject        view,
  302.     TQ3Boolean            *lightsAreTransformed);
  303.  
  304. QD3D_EXPORT TQ3Status Q3View_SetLightTransformState(
  305.     TQ3ViewObject        view,
  306.     TQ3Boolean            lightsAreTransformed);
  307.  
  308. #endif  /*  ESCHER_VER_15  */
  309.  
  310. /******************************************************************************
  311.  **                                                                             **
  312.  **                                Idle Method                                     **
  313.  **                                                                             **
  314.  *****************************************************************************/
  315. /*
  316.     The idle methods allow the application to register callback routines 
  317.     which will be called by the view during especially long operations.
  318.  
  319.     The idle methods may also be used to interrupt long renderings or
  320.     traversals.  Inside    the idler callback the application can check for
  321.     Command-Period, Control-C or clicking a "Cancel" button or whatever else
  322.     may be used to let the user interrupt rendering.    
  323.  
  324.     It is NOT LEGAL to call QD3D routines inside an idler callback.
  325.  
  326.     Return kQ3Failure to cancel rendering, kQ3Success to continue. Don't
  327.     bother posting an error.
  328.  
  329.     Q3View_SetIdleMethod registers a callback that can be called
  330.     by the system during rendering.  Unfortunately there is no way yet
  331.     to set timer intervals when you want to be called.  Basically, it is
  332.     up to the application's idler callback to check clocks to see if you
  333.     were called back only a millisecond ago or an hour ago!
  334.  
  335.     Q3View_SetIdleProgressMethod registers a callback that also gives
  336.     progress information. This information is supplied by the renderer, and
  337.     may or may not be based on real time.
  338.  
  339.     If a renderer doesn't support the progress method, your method will be
  340.     called with current == 0 and completed == 0.
  341.     
  342.     Otherwise, you are GUARANTEED to get called at least 2 or more times:
  343.     
  344.     ONCE            idleMethod(view, 0, n)        -> Initialize, Show Dialog
  345.     zero or more    idleMethod(view, 1..n-1, n) -> Update progress
  346.     ONCE            idleMethod(view, n, n)        -> Exit, Hide Dialog
  347.     
  348.     "current" is guaranteed to be less than or equal to "completed"
  349.     "completed" may change values, but current/complete always indicates
  350.     the degree of completion.
  351.  
  352.     The calling conventions aid in managing any data associated with a 
  353.     progress user interface indicator.
  354. */
  355.  
  356. typedef TQ3Status (*TQ3ViewIdleMethod)(
  357.     TQ3ViewObject        view,
  358.     const void            *idlerData);
  359.  
  360. typedef TQ3Status (*TQ3ViewIdleProgressMethod)(
  361.     TQ3ViewObject        view,
  362.     const void            *idlerData,
  363.     unsigned long        current,
  364.     unsigned long        completed);
  365.  
  366. QD3D_EXPORT TQ3Status Q3View_SetIdleMethod(
  367.     TQ3ViewObject            view,
  368.     TQ3ViewIdleMethod        idleMethod,
  369.     const void                 *idleData);
  370.  
  371. QD3D_EXPORT TQ3Status Q3View_SetIdleProgressMethod(
  372.     TQ3ViewObject                view,
  373.     TQ3ViewIdleProgressMethod    idleMethod,
  374.     const void                     *idleData);
  375.  
  376. /******************************************************************************
  377.  **                                                                             **
  378.  **                                EndFrame Method                                 **
  379.  **                                                                             **
  380.  *****************************************************************************/
  381.  
  382. /*
  383.     The end frame method is an alternate way of determining when an
  384.     asynchronous renderer has completed rendering a frame. It differs from
  385.     Q3View_Sync in that notification of the frame completion is the opposite
  386.     direction. 
  387.     
  388.     With Q3View_Sync the application asks a renderer to finish rendering
  389.     a frame, and blocks until the frame is complete.
  390.     
  391.     With the EndFrame method, the renderer tells the application that is has
  392.     completed a frame.
  393.  
  394.     If "Q3View_Sync" is called BEFORE this method has been called, this
  395.     method will NOT be called ever.
  396.     
  397.     If "Q3View_Sync" is called AFTER this method has been called, the
  398.     call will return immediately (as the frame has already been completed).
  399. */
  400.  
  401. typedef void (*TQ3ViewEndFrameMethod)(
  402.     TQ3ViewObject            view,
  403.     void                    *endFrameData);
  404.  
  405. QD3D_EXPORT TQ3Status Q3View_SetEndFrameMethod(
  406.     TQ3ViewObject            view,
  407.     TQ3ViewEndFrameMethod    endFrame,
  408.     void                     *endFrameData);
  409.  
  410. /******************************************************************************
  411.  **                                                                             **
  412.  **                            Push/Pop routines                                 **
  413.  **                                                                             **
  414.  *****************************************************************************/
  415.  
  416. QD3D_EXPORT TQ3Status Q3Push_Submit(
  417.     TQ3ViewObject     view);
  418.  
  419. QD3D_EXPORT TQ3Status Q3Pop_Submit(
  420.     TQ3ViewObject     view);
  421.  
  422.  
  423. /******************************************************************************
  424.  **                                                                             **
  425.  **        Check if bounding box is visible in the viewing frustum.  Transforms **
  426.  **        the bbox by the current local_to_world transformation matrix and     **
  427.  **        does a clip test to see if it lies in the viewing frustum.             **
  428.  **        This can be used by applications to cull out large chunks of scenes     **
  429.  **        that are not going to be visible.                                     **
  430.  **                                                                             **
  431.  **        The default implementation is to always return kQ3True.  Renderers     **
  432.  **        may override this routine however to do the checking.                 **
  433.  **                                                                             **
  434.  *****************************************************************************/
  435.  
  436. QD3D_EXPORT TQ3Boolean Q3View_IsBoundingBoxVisible(
  437.     TQ3ViewObject            view,
  438.     const TQ3BoundingBox    *bbox);
  439.  
  440.  
  441. /******************************************************************************
  442.  **                                                                             **
  443.  **                            DrawContext routines                             **
  444.  **                                                                             **
  445.  *****************************************************************************/
  446.  
  447. QD3D_EXPORT TQ3Status Q3View_SetDrawContext(
  448.     TQ3ViewObject             view,
  449.     TQ3DrawContextObject    drawContext);
  450.  
  451. QD3D_EXPORT TQ3Status Q3View_GetDrawContext(
  452.     TQ3ViewObject             view,
  453.     TQ3DrawContextObject    *drawContext);
  454.  
  455.  
  456. /******************************************************************************
  457.  **                                                                             **
  458.  **                            Graphics State routines                             **
  459.  **                                                                             **
  460.  ** The graphics state routines can only be called while rendering (ie. in     **
  461.  ** between calls to start and end rendering calls).  If they are called     **
  462.  ** outside of a rendering loop, they will return with error.                 **
  463.  **                                                                             **
  464.  *****************************************************************************/
  465.   
  466. /******************************************************************************
  467.  **                                                                             **
  468.  **                            Transform routines                                 **
  469.  **                                                                             **
  470.  *****************************************************************************/
  471.  
  472. QD3D_EXPORT TQ3Status Q3View_GetLocalToWorldMatrixState(
  473.     TQ3ViewObject        view,
  474.     TQ3Matrix4x4        *matrix);
  475.         
  476. QD3D_EXPORT TQ3Status Q3View_GetWorldToFrustumMatrixState(
  477.     TQ3ViewObject        view,
  478.     TQ3Matrix4x4        *matrix);
  479.         
  480. QD3D_EXPORT TQ3Status Q3View_GetFrustumToWindowMatrixState(
  481.     TQ3ViewObject        view,
  482.     TQ3Matrix4x4        *matrix);
  483.     
  484.  
  485. /******************************************************************************
  486.  **                                                                             **
  487.  **                            Style state routines                             **
  488.  **                                                                             **
  489.  *****************************************************************************/
  490.  
  491. QD3D_EXPORT TQ3Status Q3View_GetBackfacingStyleState(
  492.     TQ3ViewObject            view,
  493.     TQ3BackfacingStyle        *backfacingStyle);
  494.  
  495. QD3D_EXPORT TQ3Status Q3View_GetInterpolationStyleState(
  496.     TQ3ViewObject            view,
  497.     TQ3InterpolationStyle    *interpolationType);
  498.  
  499. QD3D_EXPORT TQ3Status Q3View_GetFillStyleState(
  500.     TQ3ViewObject            view,
  501.     TQ3FillStyle            *fillStyle);
  502.  
  503. QD3D_EXPORT TQ3Status Q3View_GetHighlightStyleState(
  504.     TQ3ViewObject            view,
  505.     TQ3AttributeSet            *highlightStyle);
  506.  
  507. QD3D_EXPORT TQ3Status Q3View_GetSubdivisionStyleState(
  508.     TQ3ViewObject            view,
  509.     TQ3SubdivisionStyleData    *subdivisionStyle);
  510.  
  511. QD3D_EXPORT TQ3Status Q3View_GetOrientationStyleState(
  512.     TQ3ViewObject            view,
  513.     TQ3OrientationStyle        *fontFacingDirectionStyle);
  514.  
  515. QD3D_EXPORT TQ3Status Q3View_GetReceiveShadowsStyleState(
  516.     TQ3ViewObject            view,
  517.     TQ3Boolean                *receives);
  518.  
  519. QD3D_EXPORT TQ3Status Q3View_GetPickIDStyleState(
  520.     TQ3ViewObject            view,
  521.     unsigned long            *pickIDStyle);
  522.     
  523. QD3D_EXPORT TQ3Status Q3View_GetPickPartsStyleState(
  524.     TQ3ViewObject            view,
  525.     TQ3PickParts            *pickPartsStyle);
  526.  
  527. QD3D_EXPORT TQ3Status Q3View_GetAntiAliasStyleState(
  528.     TQ3ViewObject            view,
  529.     TQ3AntiAliasStyleData    *antiAliasData);
  530.  
  531. /******************************************************************************
  532.  **                                                                             **
  533.  **                        Attribute state routines                             **
  534.  **                                                                             **
  535.  *****************************************************************************/
  536.  
  537. QD3D_EXPORT TQ3Status Q3View_GetDefaultAttributeSet(
  538.     TQ3ViewObject        view,
  539.     TQ3AttributeSet        *attributeSet);
  540.  
  541. QD3D_EXPORT TQ3Status Q3View_SetDefaultAttributeSet(
  542.     TQ3ViewObject        view,
  543.     TQ3AttributeSet        attributeSet);
  544.  
  545.  
  546. QD3D_EXPORT TQ3Status Q3View_GetAttributeSetState(
  547.     TQ3ViewObject         view,
  548.     TQ3AttributeSet        *attributeSet);
  549.  
  550. QD3D_EXPORT TQ3Status Q3View_GetAttributeState(
  551.     TQ3ViewObject         view,
  552.     TQ3AttributeType    attributeType,
  553.     void                *data);
  554.  
  555. #ifdef __cplusplus
  556. }
  557. #endif    /* __cplusplus */
  558.  
  559. #if defined(__MWERKS__)
  560.     #pragma enumsalwaysint reset
  561. #elif defined(__xlc) || defined(__xlC) || defined(__xlC__) || defined(__XLC121__)
  562.     #pragma options enum=reset
  563. #endif
  564.  
  565. #endif  /*  QD3DView_h  */
  566.