English translate funclist & More documentation for EUDObject and ExprProxy

[armoha]

https://github.com/armoha/eudplib/blob/master/docs/funclist.txt Function list documentation (Korean) for ExprProxy is only single-line and not very helpful to understand its concept.

• ExprProxy(initval) Advanced : 'Proxy' which is able to do arithmetic operation.

While EUDObject documentation has relatively more explanation, but I think we can elaborate more here.

• EUDObject() Basic unit of data to put in Payload. RawTrigger and all dataclasses like Db, inherit EUDObject, as follows:

      class Db(EUDObject):
  
          """Class for raw data object"""
  
          def __init__(self, b):
              super().__init__()
              self.content = bytes(b)
  
          def GetDataSize(self):
              return len(self.content)
  
          def WritePayload(self, pbuffer):
              pbuffer.WriteBytes(self.content)
  

  All EUDObject should implement GetDataSize, WritePayload and Evaluate methods.

  • GetDataSize : returns size of data. EUDGrp returns size of GRP in memory, and RawTrigger returns size of a trigger in memory (2408 bytes). For dynamically sized object whose size grows bigger when more you use, like EUDVarBuffer and EUDJumpBuffer, DynamicConstructed should return True, and GetDataSize must return accurate size from Allocation Phase.

  • WritePayload : writes data on Payload, using pbuffer with functions like WriteBytes, WriteByte, WriteWord, WriteDword. For example, EUDGrp writes data with pbuffer as follows ::

        def WritePayload(self, buf):
            buf.WriteBytes(b'\0\0')  # 2byte padding to align dwords at (*)
    
            # fill in grp header
            b = self._content
            fn, w, h = struct.unpack('<HHH', b[0:6])
            buf.WriteWord(fn)
            buf.WriteWord(w)
            buf.WriteWord(h)
    
            # fill in grp frame headers table
            selfaddr = self.Evaluate()
    
            for i in range(fn):
                fhoffset = 6 + 8 * i
                xoff, yoff, w, h, lto = struct.unpack(
                    '<BBBBI', b[fhoffset: fhoffset + 8])
                buf.WriteByte(xoff)
                buf.WriteByte(yoff)
                buf.WriteByte(w)
                buf.WriteByte(h)
                buf.WriteDword(lto + selfaddr)  # (*)
    
            buf.WriteBytes(b[6 + 8 * fn:])
    

    Additionally, with WriteNone you can write empty space which can be overwritten (stacked) by other data.

  • Evaluate: returns value of EUDObject when it is used in expression. By default, it returns object's memory address with GetObjectAddr. For EUDGrp, it writes 2 bytes padding on start of object for alignment, by buf.WriteBytes(b'\0\0'), so Evaluate is re-defined to return GetObjectAddr(self) + 2

        def Evaluate(self):
            return c.GetObjectAddr(self) + 2
    

TODO list

• [ ] Explain ExprProxy and EUDObject more, as dual of end-user API and backbone struct.
  • EUDArray(ExprProxy) and EUDArrayData(EUDObject)
  • EUDStruct(ExprProxy) and EUDVArray
  • DBString(ExprProxy) and DBStringData(EUDObject)
  • EUDVariable (kind of specialized ExprProxy), VariableTriggerForward(ConstExpr) and EUDVarBuffer(EUDObject)
  • EUDVArray(ExprProxy), EUDVArrayData(ConstExpr) and EUDVarBuffer(EUDObject)