src/mesa/glapi/glX_doc.py

   1 #!/usr/bin/python2
   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
  29 import glX_XML
  30 import license
  31 import sys, getopt
  32
  33
  34 class glXDocItemFactory(glX_XML.glXItemFactory):
  35         """Factory to create GLX protocol documentation oriented objects derived from glItem."""
  36
  37         def create(self, context, name, attrs):
  38                 if name == "param":
  39                         return glXDocParameter(context, name, attrs)
  40                 else:
  41                         return glX_XML.glXItemFactory.create(self, context, name, attrs)
  42
  43 class glXDocParameter(gl_XML.glParameter):
  44         def __init__(self, context, name, attrs):
  45                 self.order = 1;
  46                 gl_XML.glParameter.__init__(self, context, name, attrs);
  47
  48
  49         def packet_type(self):
  50                 """Get the type string for the packet header
  51
  52                 GLX protocol documentation uses type names like CARD32,
  53                 FLOAT64, LISTofCARD8, and ENUM.  This function converts the
  54                 type of the parameter to one of these names."""
  55
  56                 list_of = ""
  57                 if self.is_array():
  58                         list_of = "LISTof"
  59
  60                 if self.p_type.glx_name == "":
  61                         type_name = "CARD8"
  62                 else:
  63                         type_name = self.p_type.glx_name
  64
  65                 return "%s%s" % (list_of, type_name)
  66
  67         def packet_size(self):
  68                 p = None
  69                 s = self.size()
  70                 if s == 0:
  71                         a_prod = "n"
  72                         b_prod = self.p_type.size
  73
  74                         if not self.count_parameter_list and self.counter:
  75                                 a_prod = self.counter
  76                         elif self.count_parameter_list and not self.counter or self.is_output:
  77                                 pass
  78                         elif self.count_parameter_list and self.counter:
  79                                 b_prod = self.counter
  80                         else:
  81                                 raise RuntimeError("Parameter '%s' to function '%s' has size 0." % (self.name, self.context.name))
  82
  83                         ss = "%s*%s" % (a_prod, b_prod)
  84
  85                         return [ss, p]
  86                 else:
  87                         if s % 4 != 0:
  88                                 p = "p"
  89
  90                         return [str(s), p]
  91
  92 class PrintGlxProtoText(glX_XML.GlxProto):
  93         def __init__(self):
  94                 glX_XML.GlxProto.__init__(self)
  95                 self.factory = glXDocItemFactory()
  96                 self.last_category = ""
  97                 self.license = ""
  98
  99         def printHeader(self):
 100                 return
 101
 102         def body_size(self, f):
 103                 # At some point, refactor this function and
 104                 # glXFunction::command_payload_length.
 105
 106                 size = 0;
 107                 size_str = ""
 108                 pad_str = ""
 109                 plus = ""
 110                 for p in f.parameterIterator(1, 2):
 111                         [s, pad] = p.packet_size()
 112                         try:
 113                                 size += int(s)
 114                         except Exception,e:
 115                                 size_str += "%s%s" % (plus, s)
 116                                 plus = "+"
 117
 118                         if pad != None:
 119                                 pad_str = pad
 120
 121                 return [size, size_str, pad_str]
 122
 123         def print_render_header(self, f):
 124                 [size, size_str, pad_str] = self.body_size(f)
 125                 size += 4;
 126
 127                 if size_str == "":
 128                         s = "%u" % ((size + 3) & ~3)
 129                 elif pad_str != "":
 130                         s = "%u+%s+%s" % (size, size_str, pad_str)
 131                 else:
 132                         s = "%u+%s" % (size, size_str)
 133
 134                 print '            2        %-15s rendering command length' % (s)
 135                 print '            2        %-4u            rendering command opcode' % (f.glx_rop)
 136                 return
 137
 138
 139         def print_single_header(self, f):
 140                 [size, size_str, pad_str] = self.body_size(f)
 141                 size = ((size + 3) / 4) + 2;
 142
 143                 if f.glx_vendorpriv != 0:
 144                         size += 1
 145
 146                 print '            1        CARD8           opcode (X assigned)'
 147                 print '            1        %-4u            GLX opcode (%s)' % (f.opcode_real_value(), f.opcode_real_name())
 148
 149                 if size_str == "":
 150                         s = "%u" % (size)
 151                 elif pad_str != "":
 152                         s = "%u+((%s+%s)/4)" % (size, size_str, pad_str)
 153                 else:
 154                         s = "%u+((%s)/4)" % (size, size_str)
 155
 156                 print '            2        %-15s request length' % (s)
 157
 158                 if f.glx_vendorpriv != 0:
 159                         print '            4        %-4u            vendor specific opcode' % (f.opcode_value())
 160
 161                 print '            4        GLX_CONTEXT_TAG context tag'
 162
 163                 return
 164
 165         def print_reply(self, f):
 166                 print '          =>'
 167                 print '            1        1               reply'
 168                 print '            1                        unused'
 169                 print '            2        CARD16          sequence number'
 170
 171                 if f.output == None:
 172                         print '            4        0               reply length'
 173                 elif f.reply_always_array:
 174                         print '            4        m               reply length'
 175                 else:
 176                         print '            4        m               reply length, m = (n == 1 ? 0 : n)'
 177
 178
 179                 unused = 24
 180                 if f.fn_return_type != 'void':
 181                         print '            4        %-15s return value' % (f.fn_return_type)
 182                         unused -= 4
 183                 elif f.output != None:
 184                         print '            4                        unused'
 185                         unused -= 4
 186
 187                 if f.output != None:
 188                         print '            4        CARD32          n'
 189                         unused -= 4
 190
 191                 if f.output != None:
 192                         if not f.reply_always_array:
 193                                 print ''
 194                                 print '            if (n = 1) this follows:'
 195                                 print ''
 196                                 print '            4        CARD32          %s' % (f.output.name)
 197                                 print '            %-2u                       unused' % (unused - 4)
 198                                 print ''
 199                                 print '            otherwise this follows:'
 200                                 print ''
 201
 202                         print '            %-2u                       unused' % (unused)
 203                         p = f.output
 204                         [s, pad] = p.packet_size()
 205                         print '            %-8s %-15s %s' % (s, p.packet_type(), p.name)
 206                         if pad != None:
 207                                 try:
 208                                         bytes = int(s)
 209                                         bytes = 4 - (bytes & 3)
 210                                         print '            %-8u %-15s unused' % (bytes, "")
 211                                 except Exception,e:
 212                                         print '            %-8s %-15s unused, %s=pad(%s)' % (pad, "", pad, s)
 213                 else:
 214                         print '            %-2u                       unused' % (unused)
 215
 216
 217         def print_body(self, f):
 218                 for p in f.parameterIterator(1, 2):
 219                         [s, pad] = p.packet_size()
 220                         print '            %-8s %-15s %s' % (s, p.packet_type(), p.name)
 221                         if pad != None:
 222                                 try:
 223                                         bytes = int(s)
 224                                         bytes = 4 - (bytes & 3)
 225                                         print '            %-8u %-15s unused' % (bytes, "")
 226                                 except Exception,e:
 227                                         print '            %-8s %-15s unused, %s=pad(%s)' % (pad, "", pad, s)
 228
 229         def printFunction(self, f):
 230                 # At some point this should be expanded to support pixel
 231                 # functions, but I'm not going to lose any sleep over it now.
 232
 233                 if f.client_handcode or f.server_handcode or f.vectorequiv or f.image:
 234                         return
 235
 236                 print '        %s' % (f.name)
 237
 238                 if f.glx_rop != 0:
 239                         self.print_render_header(f)
 240                 else:
 241                         self.print_single_header(f)
 242
 243                 self.print_body(f)
 244
 245                 if f.needs_reply():
 246                         self.print_reply(f)
 247
 248                 print ''
 249                 return
 250
 251
 252 if __name__ == '__main__':
 253         file_name = "gl_API.xml"
 254
 255         try:
 256                 (args, trail) = getopt.getopt(sys.argv[1:], "f:")
 257         except Exception,e:
 258                 show_usage()
 259
 260         for (arg,val) in args:
 261                 if arg == "-f":
 262                         file_name = val
 263
 264         dh = PrintGlxProtoText()
 265         gl_XML.parse_GL_API( dh, file_name )