workbench/libs/mesa/src/mapi/glapi/gen/glX_doc.py

   1 #!/usr/bin/env python
   2
   3 # (C) Copyright IBM Corporation 2004, 2005
   4 # All Rights Reserved.
   5 #
   6 # Permission is hereby granted, free of charge, to any person obtaining a
   7 # copy of this software and associated documentation files (the "Software"),
   8 # to deal in the Software without restriction, including without limitation
   9 # on the rights to use, copy, modify, merge, publish, distribute, sub
  10 # license, and/or sell copies of the Software, and to permit persons to whom
  11 # the Software is furnished to do so, subject to the following conditions:
  12 #
  13 # The above copyright notice and this permission notice (including the next
  14 # paragraph) shall be included in all copies or substantial portions of the
  15 # Software.
  16 #
  17 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  19 # FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.  IN NO EVENT SHALL
  20 # IBM AND/OR ITS SUPPLIERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  21 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  22 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  23 # IN THE SOFTWARE.
  24 #
  25 # Authors:
  26 #    Ian Romanick <idr@us.ibm.com>
  27
  28 import gl_XML, glX_XML, glX_proto_common, license
  29 import sys, getopt
  30
  31
  32 class glx_doc_item_factory(glX_proto_common.glx_proto_item_factory):
  33         """Factory to create GLX protocol documentation oriented objects derived from glItem."""
  34
  35         def create_item(self, name, element, context):
  36                 if name == "parameter":
  37                         return glx_doc_parameter(element, context)
  38                 else:
  39                         return glX_proto_common.glx_proto_item_factory.create_item(self, name, element, context)
  40
  41
  42 class glx_doc_parameter(gl_XML.gl_parameter):
  43         def packet_type(self, type_dict):
  44                 """Get the type string for the packet header
  45
  46                 GLX protocol documentation uses type names like CARD32,
  47                 FLOAT64, LISTofCARD8, and ENUM.  This function converts the
  48                 type of the parameter to one of these names."""
  49
  50                 list_of = ""
  51                 if self.is_array():
  52                         list_of = "LISTof"
  53
  54                 t_name = self.get_base_type_string()
  55                 if not type_dict.has_key( t_name ):
  56                         type_name = "CARD8"
  57                 else:
  58                         type_name = type_dict[ t_name ]
  59
  60                 return "%s%s" % (list_of, type_name)
  61
  62
  63         def packet_size(self):
  64                 p = None
  65                 s = self.size()
  66                 if s == 0:
  67                         a_prod = "n"
  68                         b_prod = self.p_type.size
  69
  70                         if not self.count_parameter_list and self.counter:
  71                                 a_prod = self.counter
  72                         elif self.count_parameter_list and not self.counter or self.is_output:
  73                                 pass
  74                         elif self.count_parameter_list and self.counter:
  75                                 b_prod = self.counter
  76                         else:
  77                                 raise RuntimeError("Parameter '%s' to function '%s' has size 0." % (self.name, self.context.name))
  78
  79                         ss = "%s*%s" % (a_prod, b_prod)
  80
  81                         return [ss, p]
  82                 else:
  83                         if s % 4 != 0:
  84                                 p = "p"
  85
  86                         return [str(s), p]
  87
  88 class PrintGlxProtoText(gl_XML.gl_print_base):
  89         def __init__(self):
  90                 gl_XML.gl_print_base.__init__(self)
  91                 self.license = ""
  92
  93
  94         def printHeader(self):
  95                 return
  96
  97
  98         def body_size(self, f):
  99                 # At some point, refactor this function and
 100                 # glXFunction::command_payload_length.
 101
 102                 size = 0;
 103                 size_str = ""
 104                 pad_str = ""
 105                 plus = ""
 106                 for p in f.parameterIterateGlxSend():
 107                         [s, pad] = p.packet_size()
 108                         try:
 109                                 size += int(s)
 110                         except Exception,e:
 111                                 size_str += "%s%s" % (plus, s)
 112                                 plus = "+"
 113
 114                         if pad != None:
 115                                 pad_str = pad
 116
 117                 return [size, size_str, pad_str]
 118
 119
 120         def print_render_header(self, f):
 121                 [size, size_str, pad_str] = self.body_size(f)
 122                 size += 4;
 123
 124                 if size_str == "":
 125                         s = "%u" % ((size + 3) & ~3)
 126                 elif pad_str != "":
 127                         s = "%u+%s+%s" % (size, size_str, pad_str)
 128                 else:
 129                         s = "%u+%s" % (size, size_str)
 130
 131                 print '            2        %-15s rendering command length' % (s)
 132                 print '            2        %-4u            rendering command opcode' % (f.glx_rop)
 133                 return
 134
 135
 136         def print_single_header(self, f):
 137                 [size, size_str, pad_str] = self.body_size(f)
 138                 size = ((size + 3) / 4) + 2;
 139
 140                 if f.glx_vendorpriv != 0:
 141                         size += 1
 142
 143                 print '            1        CARD8           opcode (X assigned)'
 144                 print '            1        %-4u            GLX opcode (%s)' % (f.opcode_real_value(), f.opcode_real_name())
 145
 146                 if size_str == "":
 147                         s = "%u" % (size)
 148                 elif pad_str != "":
 149                         s = "%u+((%s+%s)/4)" % (size, size_str, pad_str)
 150                 else:
 151                         s = "%u+((%s)/4)" % (size, size_str)
 152
 153                 print '            2        %-15s request length' % (s)
 154
 155                 if f.glx_vendorpriv != 0:
 156                         print '            4        %-4u            vendor specific opcode' % (f.opcode_value())
 157
 158                 print '            4        GLX_CONTEXT_TAG context tag'
 159
 160                 return
 161
 162
 163         def print_reply(self, f):
 164                 print '          =>'
 165                 print '            1        1               reply'
 166                 print '            1                        unused'
 167                 print '            2        CARD16          sequence number'
 168
 169                 if f.output == None:
 170                         print '            4        0               reply length'
 171                 elif f.reply_always_array:
 172                         print '            4        m               reply length'
 173                 else:
 174                         print '            4        m               reply length, m = (n == 1 ? 0 : n)'
 175
 176
 177                 output = None
 178                 for x in f.parameterIterateOutputs():
 179                         output = x
 180                         break
 181
 182
 183                 unused = 24
 184                 if f.return_type != 'void':
 185                         print '            4        %-15s return value' % (f.return_type)
 186                         unused -= 4
 187                 elif output != None:
 188                         print '            4                        unused'
 189                         unused -= 4
 190
 191                 if output != None:
 192                         print '            4        CARD32          n'
 193                         unused -= 4
 194
 195                 if output != None:
 196                         if not f.reply_always_array:
 197                                 print ''
 198                                 print '            if (n = 1) this follows:'
 199                                 print ''
 200                                 print '            4        CARD32          %s' % (output.name)
 201                                 print '            %-2u                       unused' % (unused - 4)
 202                                 print ''
 203                                 print '            otherwise this follows:'
 204                                 print ''
 205
 206                         print '            %-2u                       unused' % (unused)
 207
 208                         [s, pad] = output.packet_size()
 209                         print '            %-8s %-15s %s' % (s, output.packet_type( self.type_map ), output.name)
 210                         if pad != None:
 211                                 try:
 212                                         bytes = int(s)
 213                                         bytes = 4 - (bytes & 3)
 214                                         print '            %-8u %-15s unused' % (bytes, "")
 215                                 except Exception,e:
 216                                         print '            %-8s %-15s unused, %s=pad(%s)' % (pad, "", pad, s)
 217                 else:
 218                         print '            %-2u                       unused' % (unused)
 219
 220
 221         def print_body(self, f):
 222                 for p in f.parameterIterateGlxSend():
 223                         [s, pad] = p.packet_size()
 224                         print '            %-8s %-15s %s' % (s, p.packet_type( self.type_map ), p.name)
 225                         if pad != None:
 226                                 try:
 227                                         bytes = int(s)
 228                                         bytes = 4 - (bytes & 3)
 229                                         print '            %-8u %-15s unused' % (bytes, "")
 230                                 except Exception,e:
 231                                         print '            %-8s %-15s unused, %s=pad(%s)' % (pad, "", pad, s)
 232
 233         def printBody(self, api):
 234                 self.type_map = {}
 235                 for t in api.typeIterate():
 236                         self.type_map[ "GL" + t.name ] = t.glx_name
 237
 238
 239                 # At some point this should be expanded to support pixel
 240                 # functions, but I'm not going to lose any sleep over it now.
 241
 242                 for f in api.functionIterateByOffset():
 243                         if f.client_handcode or f.server_handcode or f.vectorequiv or len(f.get_images()):
 244                                 continue
 245
 246
 247                         if f.glx_rop:
 248                                 print '        %s' % (f.name)
 249                                 self.print_render_header(f)
 250                         elif f.glx_sop or f.glx_vendorpriv:
 251                                 print '        %s' % (f.name)
 252                                 self.print_single_header(f)
 253                         else:
 254                                 continue
 255
 256                         self.print_body(f)
 257
 258                         if f.needs_reply():
 259                                 self.print_reply(f)
 260
 261                         print ''
 262                 return
 263
 264
 265 if __name__ == '__main__':
 266         file_name = "gl_API.xml"
 267
 268         try:
 269                 (args, trail) = getopt.getopt(sys.argv[1:], "f:")
 270         except Exception,e:
 271                 show_usage()
 272
 273         for (arg,val) in args:
 274                 if arg == "-f":
 275                         file_name = val
 276
 277         api = gl_XML.parse_GL_API( file_name, glx_doc_item_factory() )
 278
 279         printer = PrintGlxProtoText()
 280         printer.Print( api )