home *** CD-ROM | disk | FTP | other *** search
/ Game Programming in C++ - Start to Finish / GameProgrammingS.iso / tools_install / gDEBugger-2_1_book.msi / string_marker.txt < prev    next >
Encoding:
Text File  |  2005-06-08  |  5.1 KB  |  190 lines
  1. Name
  2.  
  3.     GREMEDY_string_marker
  4.  
  5. Name Strings
  6.  
  7.     GL_GREMEDY_string_marker
  8.  
  9. Contributors
  10.  
  11.     Dirk Reiners
  12.     Yaki Tebeka
  13.  
  14. Contact
  15.  
  16.     Dirk Reiners, Iowa State University (dreiners 'at' iastate.edu)
  17.     Yaki Tebeka, Graphic Remedy (yaki 'at' gremedy.com)
  18.  
  19. Status
  20.  
  21.     Implemented by gDEBugger (Version 1.2.1 or later)
  22.  
  23. Version
  24.  
  25.     Last Modified Date: February 1, 2005
  26.     Author Revision: 1.2
  27.  
  28. Number
  29.  
  30.     311
  31.  
  32. Dependencies
  33.  
  34.     OpenGL 1.0 is required.
  35.     
  36.     The extension is written against the OpenGL 1.5 Specification.
  37.  
  38. Overview
  39.  
  40.     This extension defines a mechanism to insert textual markers into
  41.     the OpenGL stream. 
  42.  
  43.     When debugging or profiling an OpenGL application some of the most
  44.     important tools are stream loggers, which just output a list of the
  45.     called OpenGL commands, and profilers, which show at which points
  46.     the pipeline is bottlenecked for a given part of the frame. The
  47.     problem in using these is that there is a definite loss of
  48.     information between the application and the used debugger/profiler.
  49.     The application generally has a pretty good idea what is rendered
  50.     when (e.g. rendering background, landscape, building, players,
  51.     particle effects, bullets etc.), but the debugger/profiler only
  52.     sees the OpenGL stream. To analyze the stream developers have to
  53.     guess what is done when by following the program code and the log
  54.     output in parallel, which can get difficult for systems that
  55.     restructure their internal pipeline or do lazy changes.
  56.  
  57.     This extension is really only useful for these debuggers and
  58.     profilers, and not for actual drivers. In fact, it is not expected
  59.     that any standard driver would ever implement this extension. The
  60.     main point of having this extension is to allow applications to have a
  61.     clean way of accessing this functionality only when they are run
  62.     under the control of a debugger/profiler, without having to
  63.     recompile or change the application.
  64.  
  65.  
  66. IP Status
  67.  
  68.     No known IP claims
  69.  
  70. Issues
  71.  
  72.    (1) Should the extension use \0-terminated strings to simplify use?
  73.     
  74.     RESOLVED: yes.
  75.  
  76.     This extension follows the latest precedent for strings, which is the ShaderSource().
  77.     It uses strings that are given as a list of ubytes with explicit length. However, If 
  78.     lengths is 0, then the string is assumed to be null-terminated.
  79.  
  80.  
  81.    (2) Should it be legal to call this inside Begin/End?
  82.     
  83.     RESOLVED: no.
  84.     
  85.     The benefit is questionable, and it would probably add
  86.     overhead to a very critical path.
  87.         
  88.    (3) Should this be supported by GLX?
  89.     
  90.     UNRESOLVED
  91.     
  92.     Not strictly necessary, as most debugging is done locally. It would
  93.     be cleaner, but I don't see a case for the effort. 
  94.     
  95.     
  96. New Procedures and Functions
  97.  
  98.     void StringMarkerGREMEDY(sizei len, const void *string);
  99.  
  100. New Types
  101.  
  102.     None
  103.  
  104. New Tokens
  105.  
  106.     None
  107.  
  108. Additions to Chapter 2 of the OpenGL 1.5 Specification
  109. (OpenGL Operation)
  110.  
  111.     None
  112.  
  113. Additions to Chapter 3 of the OpenGL 1.5 Specification (Rasterization)
  114.  
  115.     None
  116.  
  117. Additions to Chapter 4 of the OpenGL 1.5 Specification (Per-Fragment
  118. Operations and the Frame Buffer)
  119.  
  120.     None
  121.  
  122. Additions to Chapter 5 of the OpenGL 1.5 Specification
  123. (Special Functions)
  124.  
  125.     Add section 5.7 on page 212
  126.     
  127.     5.7 Markers
  128.     
  129.     The command
  130.     
  131.         void StringMarkerGREMEDY(sizei len, const void *string);
  132.     
  133.     can be used to insert arbitrary marker strings into the command
  134.     stream that can be recorded by appropriate debugging tools / profiling tools /
  135.     drivers. They have no influence on the rendered image or the OpenGL state.
  136.     <string> is a pointer to the array of bytes representing the marker being
  137.     inserted, which need not be null-terminated.  The length of the array is given
  138.     by <len>.  If <string> is null-terminated, <len> should not include the terminator.
  139.     If lengths is 0, then the string is assumed to be null-terminated.
  140.  
  141. Additions to Chapter 6 of the OpenGL 1.5 Specification (State and State
  142. Requests)
  143.  
  144.     None
  145.  
  146. Additions to Appendix A of the OpenGL 1.5 Specification (Invariance)
  147.  
  148.     None
  149.  
  150. Additions to the AGL/EGL/GLX/WGL Specifications
  151.  
  152.     None
  153.  
  154. GLX Protocol
  155.  
  156.     None
  157.  
  158. Dependencies on EXT_extension_name
  159.  
  160.     None
  161.  
  162. Errors
  163.  
  164.     The error INVALID_OPERATION is generated if any of the commands
  165.     defined in this extension is executed between the execution of Begin
  166.     and the corresponding execution of End.
  167.  
  168. New State
  169.  
  170.     None
  171.  
  172. New Implementation Dependent State
  173.  
  174.     None
  175.  
  176. Sample Code
  177.  
  178.     None
  179.  
  180. Revision History
  181.  
  182.     1.3, 06/08/05 yt:   - Enable the use of \0-terminated strings by specifying 
  183.                           a 0 string length.
  184.     1.2, 02/01/05 dr:   - Change the extension Status
  185.                         - Change the name of the extension 
  186.     1.1, 01/20/05 dr:     (Thanks to Yaki Tebeka for suggestions!)
  187.                         - Switched to programString style
  188.                         - renamed to marker_string  
  189.     1.0, 01/17/05 dr:   - Initial revision
  190.