home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 19 / AACD19.BIN / AACD / Programming / MCC_GLArea / MCC_GLArea_Dev / Doc / MCC_GLArea.doc
Encoding:
Text File  |  2000-12-28  |  13.8 KB  |  585 lines
  1. TABLE OF CONTENTS
  2.  
  3. GLArea.mcc/---Overview---
  4. GLArea.mcc/---ImageDB.mcc---
  5. GLArea.mcc/MUIA_GLArea_Buffered
  6. GLArea.mcc/MUIA_GLArea_DefWidth
  7. GLArea.mcc/MUIA_GLArea_DefHeight
  8. GLArea.mcc/MUIA_GLArea_DrawFunc
  9. GLArea.mcc/MUIA_GLArea_InitFunc
  10. GLArea.mcc/MUIA_GLArea_glBase
  11. GLArea.mcc/MUIA_GLArea_gluBase
  12. GLArea.mcc/MUIA_GLArea_glutBase
  13. GLArea.mcc/MUIA_GLArea_MaxHeight
  14. GLArea.mcc/MUIA_GLArea_MaxWidth
  15. GLArea.mcc/MUIA_GLArea_MinHeight
  16. GLArea.mcc/MUIA_GLArea_MinWidth
  17. GLArea.mcc/MUIA_GLArea_MouseDownFunc
  18. GLArea.mcc/MUIA_GLArea_MouseMoveFunc
  19. GLArea.mcc/MUIA_GLArea_MouseUpFunc
  20. GLArea.mcc/MUIA_GLArea_ResetFunc
  21. GLArea.mcc/MUIA_GLArea_SingleTask
  22. GLArea.mcc/MUIA_GLArea_Status
  23. GLArea.mcc/MUIA_GLArea_Threaded
  24. GLArea.mcc/MUIM_GLArea_Break
  25. GLArea.mcc/MUIM_GLArea_Init
  26. GLArea.mcc/MUIM_GLArea_Redraw
  27. GLArea.mcc/MUIM_GLArea_Reset
  28. GLArea.mcc/---Overview---
  29.  
  30.     This class is a subclass of Area. It's main purpose is to simplify StormMesa
  31.     context manipulation and to implement an easy way of integration of
  32.     3D graphics in MUI User Interfaces.
  33.  
  34.     Another goal was to write a "threaded" rendering system, because of the
  35.     complexity of OpenGL rendering (slow rendering), it's a good idea to do all
  36.     this rendering in sub-processes. The developer doesn't need to care about inter-process
  37.     communication at all, everything is controlled by the GLArea class.
  38.  
  39.     Each GLArea object will create a sub-process (unless you use the SingleTask
  40.     attribut) and talk with it via signals and shared variables.
  41.     When the object should be redrawn or something else, the GLArea object will
  42.     send commands to his sub-process.
  43.  
  44.     You tell each GLArea object which function will be called for
  45.     drawing/initialising/reseting/mouse events. All these functions needs to
  46.     set their respective StormMesa library base pointer, which are opened by the sub-process.
  47.     These values are always passed as argument to your functions, (see struct
  48.     GLContext in the include files for more details).
  49.  
  50.     The rendering functions *MUST* handle break signals (SIGBREAKF_CTRL_D)
  51.     for correct threads communications. If the function was breaked
  52.     you *HAVE TO RETURN TRUE*, else return FALSE (if an incorrect value is returned,
  53.     dead-locks may happen).
  54.  
  55.     Here is an example of a single gl draw function
  56.  
  57.     Ex:
  58.     int DrawGL(struct GLContext *glcontext) {
  59.         struct Library *glBase=glcontext->gl_Base;
  60.         struct Library *gluBase=glcontext->glu_Base;
  61.         struct Library *glutBase=glcontext->glut_Base;
  62.  
  63.         //--- your gl stuff ---
  64.  
  65.         //--- ALWAYS Add this kind of line at the end of your rendering function
  66.         if (CheckSignal(SIGBREAKF_CTRL_D) return TRUE
  67.  
  68.         return FALSE
  69.     }
  70.  
  71.     This function will be called by the GLArea sub-process.
  72.  
  73. GLArea.mcc/---ImageDB.mcc---
  74.  
  75.     ImageDB.mcc is another class very usful for GLArea.mcc
  76.  
  77.     ImageDB will take care of textures manipulation needed for OpenGL renderings.
  78.  
  79. GLArea.mcc/MUIA_GLArea_Buffered
  80.  
  81.   NAME
  82.     MUIA_GLArea_Buffered -- [ISG], BOOL
  83.  
  84.   FUNCTION
  85.     Defines if the object uses GL buffering mode.
  86.     Should always be TRUE.
  87.  
  88.   DEFAULT VALUE
  89.     TRUE
  90.  
  91.   BUGS
  92.     Seems to make no difference if bufferd mode is on or not (?)
  93.  
  94.   SEE ALSO
  95.  
  96. GLArea.mcc/MUIA_GLArea_DefWidth
  97.  
  98.   NAME
  99.     MUIA_GLArea_DefWidth -- [ISG], int
  100.  
  101.   FUNCTION
  102.     Define the default width of the GL context
  103.  
  104.   DEFAULT VALUE
  105.     320
  106.  
  107.   BUGS
  108.     No known bugs.
  109.  
  110.   SEE ALSO
  111.     MUIA_GLArea_MaxWidth, etc...
  112.  
  113. GLArea.mcc/MUIA_GLArea_DefHeight
  114.  
  115.   NAME
  116.     MUIA_GLArea_DefHeight -- [ISG], int
  117.  
  118.   FUNCTION
  119.     Define the default height of the GL context
  120.  
  121.   DEFAULT VALUE
  122.     240
  123.  
  124.   BUGS
  125.     No known bugs.
  126.  
  127.   SEE ALSO
  128.  
  129.     MUI_GLArea_DefWidth, MUIA_GLArea_MaxWidth, etc...
  130. GLArea.mcc/MUIA_GLArea_DrawFunc
  131.  
  132.   NAME
  133.     MUIA_GLArea_DrawFunc -- [ISG], (PF*)
  134.  
  135.   FUNCTION
  136.     Define the rendering function. Each time the object should be redrawn,
  137.     this function is called. This function receives as its only argument a
  138.     struct GLContext pointer which contains some usful information.
  139.  
  140.     This functions has to handle SIGBREAKF_CTRL_D signals.
  141.  
  142.     Ex:
  143.     int DrawGL(struct GLContext *glcontex) {
  144.         struct Library *glBase=glcontext->gl_Base;
  145.         struct Library *gluBase=glcontext->glu_Base;
  146.         struct Library *glutBase=glcontext->glut_Base
  147.  
  148.         ...
  149.  
  150.         //--- if breaked return TRUE (1) ---
  151.         if (CheckSignal(SIGBREAKF_CTRL_D)) return 1;
  152.         //--- else return FALSE (0) ---
  153.         return 0;
  154.     }
  155.  
  156.   BUGS
  157.     No known bugs.
  158.  
  159.   SEE ALSO
  160. GLArea.mcc/MUIA_GLArea_InitFunc
  161.  
  162.   NAME
  163.     MUIA_GLArea_InitFunc -- [ISG], (PF*)
  164.  
  165.   FUNCTION
  166.     Define the GL context initialising function. Each time the object
  167.     should be initialised (MUIM_Show method), this function is called.
  168.  
  169.     This function receive as its only argument a struct GLContext pointer
  170.     which contains useful information.
  171.  
  172.     Ex:
  173.     int InitGL(struct GLContext *glcontex) {
  174.         struct Library *glBase=glcontext->gl_Base;
  175.         struct Library *gluBase=glcontext->glu_Base;
  176.         struct Library *glutBase=glcontext->glut_Base
  177.  
  178.         ...
  179.  
  180.         return FALSE;
  181.     }
  182.  
  183.   SPECIAL VALUES
  184.  
  185.     MUIV_GLArea_InitFunc_Standard
  186.  
  187.         A default Init function is called, here is the code
  188.  
  189.         GLfloat lightDirection[4]={5.0,5.0,5.0,1.0};
  190.         GLfloat diffuseColor[4]={1.0,1.0,1.0,1.0};
  191.         GLfloat ambientColor[4]={0.2,0.2,0.2,1.0};
  192.  
  193.         glLightModeli (GL_LIGHT_MODEL_LOCAL_VIEWER, GL_TRUE);
  194.         glEnable (GL_DEPTH_TEST);
  195.         glEnable (GL_LIGHTING);
  196.         glShadeModel(GL_SMOOTH);
  197.         glLightfv (GL_LIGHT0,GL_AMBIENT,ambientColor);
  198.         glLightfv (GL_LIGHT0,GL_DIFFUSE,diffuseColor);
  199.         glLightfv (GL_LIGHT0,GL_POSITION,lightDirection);
  200.         glEnable (GL_LIGHT0);
  201.         glFrontFace(GL_CCW);
  202.         glDisable(GL_CULL_FACE);
  203.         glDisable(GL_LIGHT1);
  204.         glDisable(GL_LIGHT2);
  205.         glDisable(GL_LIGHT3);
  206.         glDisable(GL_LIGHT4);
  207.         glDisable(GL_DITHER);
  208.         glPolygonMode(GL_FRONT_AND_BACK, GL_FILL);
  209.         glEnable (GL_NORMALIZE);
  210.         glClearColor(0.0,0.0,0.0,1.0);
  211.         glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
  212.         glMatrixMode (GL_PROJECTION);
  213.         glLoadIdentity();
  214.         gluPerspective (40.0,1.333,0.1,6000.0);
  215.         glMatrixMode (GL_MODELVIEW);
  216.         glLoadIdentity();
  217.  
  218.   BUGS
  219.     No known bugs.
  220.  
  221.   SEE ALSO
  222. GLArea.mcc/MUIA_GLArea_glBase
  223.  
  224.   NAME
  225.     MUIA_GLArea_glBase -- [..G], (struct Library *)
  226.  
  227.   FUNCTION
  228.     Return the glBase library pointer of this MUI app task
  229.     (also not this object sub-process library base).
  230.  
  231.     When the first GLArea object is created, it opens the
  232.     StormMesa libraries for the MUI application.
  233.     So you could retreive the glBase,gluBase,glutBase to work
  234.     with it in another environment than the GLArea object.
  235.  
  236.     If you want, you could then handle yourself all the GL context
  237.     switches using the retured library base without the help
  238.     of the GLArea object.
  239.  
  240.   BUGS
  241.     No known bugs.
  242.  
  243.   SEE ALSO
  244.     MUIA_GLArea_gluBase, MUIA_GLArea_glutBase
  245. GLArea.mcc/MUIA_GLArea_gluBase
  246.  
  247.   NAME
  248.     MUIA_GLArea_gluBase -- [..G], (struct Library *)
  249.  
  250.   FUNCTION
  251.     Return the gluBase library pointer of the MUI main task.
  252.  
  253.   BUGS
  254.     No known bugs.
  255.  
  256.   SEE ALSO
  257.     MUIA_GLArea_glBase
  258. GLArea.mcc/MUIA_GLArea_glutBase
  259.  
  260.   NAME
  261.     MUIA_GLArea_glutBase -- [..G], (struct Library *)
  262.  
  263.   FUNCTION
  264.     Return the glutBase library pointer of the MUI main task.
  265.  
  266.   BUGS
  267.     No known bugs.
  268.  
  269.   SEE ALSO
  270.     MUIA_GLArea_glBase
  271. GLArea.mcc/MUIA_GLArea_MaxHeight
  272.  
  273.    NAME
  274.     MUIA_GLArea_MaxHeight -- [ISG], int
  275.  
  276.  
  277.   FUNCTION
  278.     Define the maximum height of the GL context
  279.  
  280.   DEFAULT VALUE
  281.     600
  282.  
  283.   BUGS
  284.     No known bugs.
  285.  
  286.   SEE ALSO
  287.  
  288.     MUI_GLArea_DefWidth, MUIA_GLArea_MaxWidth, etc...
  289. GLArea.mcc/MUIA_GLArea_MaxWidth
  290.  
  291.    NAME
  292.     MUIA_GLArea_MaxWidth -- [ISG], int
  293.  
  294.  
  295.   FUNCTION
  296.     Define the maximum width of the GL context
  297.  
  298.   DEFAULT VALUE
  299.     800
  300.  
  301.   BUGS
  302.     No known bugs.
  303.  
  304.   SEE ALSO
  305.  
  306.     MUI_GLArea_DefWidth, MUIA_GLArea_MaxWidth, etc...
  307. GLArea.mcc/MUIA_GLArea_MinHeight
  308.  
  309.   NAME
  310.     MUIA_GLArea_MinWidth -- [ISG], int
  311.  
  312.   FUNCTION
  313.     Define the minimum height of the GL context
  314.  
  315.   DEFAULT VALUE
  316.     60
  317.  
  318.   BUGS
  319.     No known bugs.
  320.  
  321.   SEE ALSO
  322.  
  323.     MUI_GLArea_DefWidth, MUIA_GLArea_MaxWidth, etc...
  324. GLArea.mcc/MUIA_GLArea_MinWidth
  325.  
  326.   NAME
  327.     MUIA_GLArea_MinWidth -- [ISG], int
  328.  
  329.   FUNCTION
  330.     Define the minimum width of the GL context
  331.  
  332.   DEFAULT VALUE
  333.     80
  334.  
  335.   BUGS
  336.     No known bugs.
  337.  
  338.   SEE ALSO
  339.  
  340.     MUI_GLArea_DefWidth, MUIA_GLArea_MaxWidth, etc...
  341. GLArea.mcc/MUIA_GLArea_MouseDownFunc
  342.  
  343.   NAME
  344.     MUIA_GLArea_MouseDownFunc -- [ISG], (PFD*)
  345.  
  346.   FUNCTION
  347.     Define the GL context mouse down function. When the mouse is clicked
  348.     in the GL context, this function will be called with a
  349.     struct GLContext pointer, and the x,y coordinate of the mouse.
  350.  
  351.     The GLArea object WILL NOT call the DrawFunc, only the MouseDonwFunc is
  352.     called when the mouse is hit.
  353.  
  354.     Ex:
  355.     int MouseDownGL(int x, int y, struct GLContext *glcontex) {
  356.         struct Library *glBase=glcontext->gl_Base;
  357.         struct Library *gluBase=glcontext->glu_Base;
  358.         struct Library *glutBase=glcontext->glut_Base
  359.  
  360.         //--- use x,y ---
  361.  
  362.         return 0;
  363.     }
  364.  
  365.   BUGS
  366.     No known bugs.
  367.  
  368.   SEE ALSO
  369. GLArea.mcc/MUIA_GLArea_MouseMoveFunc
  370.  
  371.   NAME
  372.     MUIA_GLArea_MouseMoveFunc -- [ISG], (PFD*)
  373.  
  374.   FUNCTION
  375.     Define the GL context mouse move function. When the mouse is moved
  376.     AFTER the mouseclick (MouseDownFunc) in the GL context, this function
  377.     will be called with a struct GLContext pointer, and the dx,dy coordinate
  378.     of the mouse (relative coordinate to the point where MouseDownFunc was
  379.     called).
  380.  
  381.     The DrawFunc WILL NOT be called after this one.
  382.  
  383.     Ex:
  384.     int MouseMoveGL(int dx, int dy, struct GLContext *glcontex) {
  385.         struct Library *glBase=glcontext->gl_Base;
  386.         struct Library *gluBase=glcontext->glu_Base;
  387.         struct Library *glutBase=glcontext->glut_Base
  388.  
  389.         ...
  390.  
  391.         return 0;
  392.     }
  393.  
  394.   BUGS
  395.     No known bugs.
  396.  
  397.   SEE ALSO
  398. GLArea.mcc/MUIA_GLArea_MouseUpFunc
  399.  
  400.   NAME
  401.     MUIA_GLArea_MouseUpFunc -- [ISG], (PFD*)
  402.  
  403.   FUNCTION
  404.     When the mouse is released this function will be called.
  405.     The function will be called with a struct GLContext pointer,
  406.     and the x,y coordinate of the mouse.
  407.  
  408.     DrawFunc WILL be called after this one automatically.
  409.  
  410.     Ex:
  411.     int MouseUpGL(int x, int y, struct GLContext *glcontex) {
  412.         struct Library *glBase=glcontext->gl_Base;
  413.         struct Library *gluBase=glcontext->glu_Base;
  414.         struct Library *glutBase=glcontext->glut_Base
  415.  
  416.         ...
  417.  
  418.         return FALSE;
  419.     }
  420.  
  421.   BUGS
  422.     No known bugs.
  423.  
  424.   SEE ALSO
  425. GLArea.mcc/MUIA_GLArea_ResetFunc
  426.  
  427.   NAME
  428.     MUIA_GLArea_ReseteFunc -- [ISG], (PF*)
  429.  
  430.   FUNCTION
  431.     Define the GL context reset function..
  432.     This function receives as its only argument a struct GLContext
  433.     pointer.
  434.  
  435.     Ex:
  436.     int ResetGL(struct GLContext *glcontex) {
  437.         struct Library *glBase=glcontext->gl_Base;
  438.         struct Library *gluBase=glcontext->glu_Base;
  439.         struct Library *glutBase=glcontext->glut_Base
  440.  
  441.         //--- Some OpenGL reset functions
  442.  
  443.         return FALSE;
  444.     }
  445.  
  446.   BUGS
  447.     No known bugs.
  448.  
  449.   SEE ALSO
  450. GLArea.mcc/MUIA_GLArea_SingleTask
  451.  
  452.   NAME
  453.     MUIA_GLArea_SingleTask -- [I.G], BOOL
  454.  
  455.   FUNCTION
  456.     Define if the GLArea object spawn a sub-process for the rendering.
  457.  
  458.     If this value is FALSE then a new process is
  459.     created (you could then choose to do a threaded rendering or
  460.     not).
  461.  
  462.     If this value is TRUE, no new process is created and the rendering
  463.     will always be in non-threaded mode. All GUI will block until the
  464.     rendering is done. Use this attribut if you are sure that the rendering
  465.     is fast enough, so you avoid all overheads of inter-process communication.
  466.  
  467.   DEFAULT
  468.     FALSE
  469.  
  470.   BUGS
  471.     No known bugs.
  472.  
  473.   SEE ALSO
  474. GLArea.mcc/MUIA_GLArea_Status
  475.  
  476.   NAME
  477.     MUIA_GLArea_Status -- [..G], int
  478.  
  479.   FUNCTION
  480.     Define the GLArea sub-process rendering status.
  481.  
  482.   OUTPUT
  483.     MUIV_GLArea_Ready
  484.         The sub-process is ready for a new rendering
  485.  
  486.     MUIV_GLArea_Busy
  487.         The sub-process is already rendering something
  488.  
  489.     MUIV_GLArea_NotActive
  490.         The sub-process is not active (Not sub-process rendering)
  491.         You obtain this values when SingleTask is TRUE
  492.  
  493.   BUGS
  494.     No known bugs.
  495.  
  496.   SEE ALSO
  497. GLArea.mcc/MUIA_GLArea_Threaded
  498.  
  499.   NAME
  500.     MUIA_GLArea_Threaded -- [ISG], BOOL
  501.  
  502.   FUNCTION
  503.     Define if the rendering should be threaded when using sub-processes.
  504.  
  505.     When the rendering is threaded, the sub-process will render
  506.     the DrawFunc, but the GLArea object and the MUI App could
  507.     continue to work (The user interface is not blocked during
  508.     the rendering).
  509.  
  510.     If the rendering is not threaded, the sub-process will render
  511.     the DrawFunc (also, the sub-process will render the func in
  512.     all case), but will block the GLArea object and the MUI App
  513.     (the MUI Interface is freezed) until the rendering is done.
  514.  
  515.     Setting this attribut let you switch between threaded/non threaded
  516.     rendering at any moment (See GLArea_Demo program).
  517.  
  518.   DEFAULT VALUE
  519.     TRUE
  520.  
  521.   BUGS
  522.     No known bugs.
  523.  
  524.   SEE ALSO
  525. GLArea.mcc/MUIM_GLArea_Break
  526.  
  527.   NAME
  528.     MUIM_GLArea_Break
  529.  
  530.   FUNCTION
  531.     Breaks a busy GLArea subprocess.
  532.     A signal SIGBREAKF_CTRL_D is send to the sub-process.
  533.  
  534.     Has no effect when SingleTask is TRUE.
  535.  
  536.   BUGS
  537.     No known bugs.
  538.  
  539.   SEE ALSO
  540. GLArea.mcc/MUIM_GLArea_Init
  541.  
  542.   NAME
  543.     MUIM_GLArea_Init
  544.  
  545.   FUNCTION
  546.     Call the init func. If the object (sub-process) is busy, it will break it.
  547.  
  548.  BUGS
  549.     No known bugs.
  550.  
  551.   SEE ALSO
  552. GLArea.mcc/MUIM_GLArea_Redraw
  553.  
  554.   NAME
  555.     MUIM_GLArea_Redraw
  556.  
  557.   SYNOPSIS
  558.     DoMethod(obj,MUIM_GLArea_Redraw);
  559.  
  560.   FUNCTION
  561.     Call the draw func. If the object is busy, it will break it and
  562.     redraw the DrawFunc.
  563.  
  564.   BUGS
  565.     No known bugs.
  566.  
  567.   SEE ALSO
  568. GLArea.mcc/MUIM_GLArea_Reset
  569.  
  570.   NAME
  571.     MUIM_GLArea_Reset
  572.  
  573.   SYNOPSIS
  574.     DoMethod(obj,MUIM_GLArea_Reset);
  575.  
  576.   FUNCTION
  577.     Call the reset func. If the object is busy, it will break it.
  578.  
  579.   BUGS
  580.     No known bugs.
  581.  
  582.   SEE ALSO
  583.  
  584.  
  585.