--------------------------------------------------------------------------------
--
--  NAME:  BINARY_ENCODER
--  DISCREPANCY REPORTS:
--
--------------------------------------------------------------------------------
-- file: BIN_ENCODER.ADA
-- level: 0a

with CGM_STANDARD_TYPES;
with CGM_BYTE_TYPES;
                                                                    
package BINARY_ENCODER is       

-- This package contains the lowest level of routines designed to 
-- take CGM element data and encode it in a binary format returning 
-- a variable length array of bytes containing the encoded data.

---------------------------------------------------------------------------
                                                        
  procedure ENCODE_INTEGER_AS_16_BIT_INTEGER
     ( VALUE  : in INTEGER;
       RESULT : out CGM_BYTE_TYPES.BYTE_ARRAY_RECORD );

  -- Abstract symbol "E" (enumerated type) is always encoded as
  -- a 16 bit signed integer.

---------------------------------------------------------------------------

  procedure ENCODE_VDC_COORDINATE
     ( VALUE  : in  CGM_STANDARD_TYPES.VDC_COORDINATE_TYPE;
       RESULT : out CGM_BYTE_TYPES.BYTE_ARRAY_RECORD );

  -- Abstract symbol "VDC" is encoded as an integer at VDC integer 
  -- precision if the VDC type in the current generator state list 
  -- is integer; otherwise, the VDC real format (float or fixed) and 
  -- the VDC real precision determine how the value is encoded.

---------------------------------------------------------------------------

  procedure ENCODE_REAL
     ( ENCODE_VALUE  : in  CGM_STANDARD_TYPES.CGM_REAL;
       RESULT        : out CGM_BYTE_TYPES.BYTE_ARRAY_RECORD );

  -- The real format (float or fixed) and the real precision 
  -- (16 or 32 bit) determine how the value is encoded and how many 
  -- bytes will be returned. 
            
---------------------------------------------------------------------------

  procedure ENCODE_ELEMENT_HEADER
     ( OPCODE : in  CGM_STANDARD_TYPES.CGM_ELEMENTS;
       LENGTH : in  CGM_STANDARD_TYPES.CGM_INTEGER;
       RESULT : out CGM_BYTE_TYPES.BYTE_ARRAY_RECORD );

  -- The opcode and parameter list length are used to return either 
  -- a short or long-form element header encoded in an array of bytes.

---------------------------------------------------------------------------

  procedure ENCODE_HEADER
     ( OPCODE : in  CGM_STANDARD_TYPES.CGM_ELEMENTS;
       RESULT : out CGM_BYTE_TYPES.BYTE_ARRAY_RECORD );

  -- The opcode is used to return the 1st word of a 
  -- long-form element header encoded in an array of bytes.

---------------------------------------------------------------------------
                                             
  procedure ENCODE_PARTITION
     ( LENGTH : in  CGM_STANDARD_TYPES.CGM_INTEGER;
       RESULT : out CGM_BYTE_TYPES.BYTE_ARRAY_RECORD;
       FINAL  : in  BOOLEAN := FALSE);
  -- The parameter list length and final flag are used 
  -- to return a partition word in an array of bytes. This
  -- word is used as the 2nd word of a long-form element header 
  -- or between the element's data when there is more data than
  -- will fit in a single partition.

---------------------------------------------------------------------------

  procedure ENCODE_STRING                             
     ( ENCODE_STRING : in  STRING;          
       RESULT        : out CGM_BYTE_TYPES.BYTE_ARRAY_RECORD;
       FINAL         : out BOOLEAN;
       INITIAL       : in  BOOLEAN := FALSE);

  -- In the binary format, strings are encoded as a length 
  -- followed by the characters in the string. Strings of
  -- 254 characters or less require 1 octet (byte) to encode
  -- the length. Longer strings use 3 octets. The 1st contains
  -- 255 and the next 2 contain a 1 bit continuation flag 
  -- and a 15 bit length. A 0 flag means end of string and a
  -- 1 flag means there is another 2 octet length and "n" 
  -- number of characters following this one. Thus, the length
  -- is like partitions used for parameter list lengths in
  -- element headers.

---------------------------------------------------------------------------

  procedure ENCODE_COLOUR_INDEX                            
     ( ENCODE_VALUE : in  CGM_STANDARD_TYPES.CGM_INTEGER;
       RESULT       : out CGM_BYTE_TYPES.BYTE_ARRAY_RECORD );

  -- Encoded as an integer using the colour index precision in the
  -- current generator state list.
                                                        
---------------------------------------------------------------------------

  procedure ENCODE_COLOUR_DIRECT
     ( ENCODE_VALUE : in  CGM_STANDARD_TYPES.CGM_INTEGER;
       RESULT       : out CGM_BYTE_TYPES.BYTE_ARRAY_RECORD );

  -- Encoded as an integer using the colour direct precision in the
  -- current generator state list.
  -- NOTE: the colour direct precision is related directly to the
  --       CGM colour precision element.

---------------------------------------------------------------------------

  procedure ENCODE_INDEX
     ( ENCODE_VALUE : in  CGM_STANDARD_TYPES.CGM_INTEGER;
       RESULT       : out CGM_BYTE_TYPES.BYTE_ARRAY_RECORD );

  -- Encoded as an integer using the index precision in the
  -- current generator state list.
                                                
---------------------------------------------------------------------------

  procedure ENCODE_SIGNED_INTEGER
     ( ENCODE_VALUE : in  CGM_STANDARD_TYPES.CGM_INTEGER;
       RESULT       : out CGM_BYTE_TYPES.BYTE_ARRAY_RECORD );

  -- Encoded as an integer using the integer precision in the
  -- current generator state list.
                                               
---------------------------------------------------------------------------

  procedure ENCODE_ELEMENT_CLASS_AND_CODE
     ( ELEMENT : in  CGM_STANDARD_TYPES.CGM_ELEMENTS;
       RESULT  : out CGM_BYTE_TYPES.BYTE_ARRAY_RECORD );

  -- The metafile descriptor element: METAFILE_ELEMENT_LIST requires 
  -- the class and code of supported elements be encoded using index 
  -- precision for it's parameters. This routine builds and returns 
  -- those parameters.

---------------------------------------------------------------------------
  
end BINARY_ENCODER;