




















                                     POB-SDK















         Author:   Thomas Baier

         EMail:    thbaier@compuserve.com

         CIS:  100527, 3011

         WWW:  http://ourworld.compuserve.com/homepages/thbaier



         Revision 0.8, 06/97



         Revision 0.8, 06/97         POB-SDK                           2
          ______________________________________________________________

         Table Of Contents



         1 INTRODUCTION ...............................................3


         2 WHY ANOTHER GRAPHICS FILE FORMAT ? .........................3


         3 APPLICATIONS ...............................................4


         4 CONTENTS OF POB-SDK ........................................5

           4.1 POV-Ray to POB Converter ...............................5
           4.2 POB Reader .............................................5

         5 POB SPECIFICATION ..........................................6

           5.1 Chunk Definition .......................................6
           5.2 Chunk Layout with examples .............................7
           5.3 POB Chunk Identifiers .................................13
           5.4 POB Data Types ........................................19
           5.5 Limitations of POB ....................................30

         6 PLATFORM NOTES ............................................30


         7 SAMPLE POB_RD.EXE SESSION .................................31


         8 SOURCE CODE DESCRIPTION ...................................33

           8.1 POBWRITE.C: ...........................................33
           8.2 POB_RD.C ..............................................33

         9 BUILDING POVRAY.EXE (MSDOS) ...............................34


         10 BUILDING POB_RD.EXE (MSDOS) ..............................35


         11 DEVELOPING A POB WRITER ..................................35


         12 DEVELOPING A POB READER ..................................35


         13 SYSTEM REQUIREMENTS ......................................35


         14 COPYRIGHT ................................................35


         15 ACKNOWLEDGEMENTS .........................................36




         10.06.97     Thomas Baier <thbaier@compuserve.com>       Page 2



         Revision 0.8, 06/97         POB-SDK                           3
          ______________________________________________________________






         1 Introduction

         The POB (POV-Ray Binary) format is a file format which handles
         all scene elements of  POV-Ray 3.0. The file format is binary
         and chunk oriented (like the 3D Studio format) and allows easy
         handling of all or specific scene elements. It is designed to
         be platform independent and should easily be usable on just
         about all platforms.

         The POB format is supported by the POB-SDK, which provides:

           . a modified version of POVRAY.EXE, which easily converts
             POV-Ray files (version 1, 2, and 3) to the POB format.

           . Freely usable sample code for examining/debugging POB-files
             and writing back POV-Ray files.

           . A specification of the POB-file format.

         Currently, the POB format supports only a snapshot of a POV
         file for a single "clock" value. This may change in the future.




         2 Why another graphics file format ?

         Although POV-Ray is one of  the most popular free 3d-graphics-
         program there is no other program, that can parse all POV-Ray
         scenes correctly. The author had also attempted this feat with
         POV2MDL (a POV-Ray to MORAY-converter), but with only partial
         success.

         There is no way to import and reprocess a POV-Ray-source with
         any modeller (e.g. MORAY or 3D-Studio).

         This is a pity, if you think about the high-class POV-Ray-
         scenes that are out there like Mike Miller's famous Nikon-
         Camera.

         Why is no 3rd-party-program able to read POV-Ray-sources ?

         POV-Ray defines not only a POV-file-format, but also a complex
         syntax (similar to "C_ or "PASCAL_) to describe a POV-Ray-
         scene. POV-Ray itself contains a parser (similar to the parser
         of a "C_-compiler) for decoding the POV-Ray-language. There is
         source-code for this parser, but there are some limitations
         using it.







         10.06.97     Thomas Baier <thbaier@compuserve.com>       Page 3



         Revision 0.8, 06/97         POB-SDK                           4
          ______________________________________________________________

         One could try to write ones own parser without using POV-Ray-
         code. The author tried it, but with little success. There are
         helpful tools like LEX&YACC for writing parsers, but there are
         some minimum requirements for  a  language to be handled with a
         automatically generated and verified parser.  "C_ or "PASCAL_
         meet this requirement, but POV-Ray does not. The author wrote a
         parser with LEX&YACC, but only a  part of the POV-Ray-language
         was supported. There were many problems, especially with older
         scenes.

         Is the dream over to reprocess POV-Ray-sources ?

         No, if you take a different route. There is no application that
         reads POV-files better than POV-Ray itself. Fortunately, the
         POV-license makes it possible to carry out modifications on the
         source code and distribute the changed version as long as one
         passes complete source code on.

         This is my idea:

         . Define a file-format that covers the full complexity of all
           previous and future POV-Ray versions and that is simple to
           read by other applications.

         . Modify  the source code of POV-Ray in such a way that it can
           write the new file-format.

         . Publish sample source code to read and write the new file-
           format.

         This procedure has two important advantages:

         . There is a 100% POV-Ray to "new file format_ converter. All
           POV-Ray instructions are recognized. Future versions of POV-
           Ray will (hopefully) have this converter built in for new
           features.

         . Sample code for a reader is available for free. There is a
           detailed specification for the new file-format. Reader-code
           and specification do not follow POVLEGAL but the more
           generous POB-license. Commercial products can use POB-format
           without any restriction. POB-reader code is free.




         3 Applications

         All you need to do to enable your application to read POV files
         is to implement a POB-Reader. Creating the POB-files from
         POV-Ray-files is very easy and is done by a modified
         POV-Ray 3.01 version.








         10.06.97     Thomas Baier <thbaier@compuserve.com>       Page 4



         Revision 0.8, 06/97         POB-SDK                           5
          ______________________________________________________________

         If you have developed a POV-Ray texture designer or a POV-Ray
         modeller, it is easy for your application to read information
         from the POB files. It does not matter if your application does
         not support all POV-Ray features. You can simply jump over
         unsupported scene elements without knowing their internal
         details.




         4 Contents of POB-SDK



         4.1 POV-Ray to POB Converter

         The POB-SDK contains a modified POV-Ray 3.01 version for MSDOS
         with source code (please read POVLEGAL.DOC).

         The executable can be found in POB_SDK\BIN\POVRAY.EXE. It
         generates POB-files from POV-Ray files by using the switch
         "Output_File_Type=x_. The directory POB_SDK\BIN\ also contains
         the file "PARSE.INI_, in which you need to set the POV-Ray
         include paths. The last two lines in this file are used to
         instruct POV-Ray to create a POB-file.

         POB is integrated "seamlessly_ into POV-Ray. If you want to
         render a scene you can choose either "TGA_ or "POB_ as the
         output format. The modified POV-Ray-version evaluates first all
         conditionals and the clock-variable and then it writes the POB-
         file. It is similar to "TGA_-output. Before rendering, POV-Ray
         evaluates the whole scene.

         If you want a POV-Ray to POB-Converter on other platforms than
         Intel please refer to Chapter 6.



         4.2 POB Reader

         The executable POB_SDK\BIN\POB_RD.EXE (MSDOS) reads in a POB-
         file and writes a POV-Ray-file. POB_RD.EXE writes to stdout.

         Example:

              POB_RD TEST.POB > TEST.POV

         Additionally a log-file is written (POB.LOG), which makes
         debugging of POB-files easier.

         Full source code for POB_RD.EXE is provided in POB_SDK\SAMPLE.

         For other platforms than Intel please refer to Chapter 6.







         10.06.97     Thomas Baier <thbaier@compuserve.com>       Page 5



         Revision 0.8, 06/97         POB-SDK                           6
          ______________________________________________________________

         5 POB Specification

         This chapter describes the chunk oriented file format. A lot of
         commercial 3D programs such as 3D Studio, Imagine and Lightwave
         use similar formats. All the contents of a POB-file are stored
         in binary form.

         Chunk-oriented file-formats have the following advantages:

         . Data can be stored in a "flat_ structure

         . Data can be stored in a tree-structure using Subchunks,
           similar to a file-system. The Parent Chunk is similar to a
           directory, Parent Chunk Data can be compared with files and
           Child Chunks with subdirectories.

         . Reading chunk-oriented files is very effective. Only the
           Chunk Header has to be checked to determine whether the data
           needs to be read.

         . Unimportant or unknown data and Child Chunks can be skipped
           over efficiently.



         5.1 Chunk Definition

         A chunk consists of a Chunk Header and Chunk Data.


         5.1.1 Chunk Header

         The Chunk Header consists of a Chunk Identifier and a Chunk
         Length. The Chunk Header is 6 bytes long. 2 bytes are used for
         the Chunk Identifier and the other 4 are used for the Chunk
         Length.


         5.1.2 Chunk Identifier

         The 2 Bytes of the Chunk Identifier are treated as a WORD
         (little endian, low byte/high byte).

         The Chunk Identifier is unique and identifies the type of  the
         chunk and thus also the layout of the Chunk Data.


         5.1.3 Chunk Length

         The 4 Bytes of the Chunk Length are interpreted as a DWORD
         (little endian, low byte/high byte).

         The Chunk Length is calculated from the length of the
         Chunk Header and the length of the Chunk Data. It includes the
         chunk itself, i.e. the length is counted from the start of the
         chunk to the last byte of the chunk.




         10.06.97     Thomas Baier <thbaier@compuserve.com>       Page 6



         Revision 0.8, 06/97         POB-SDK                           7
          ______________________________________________________________

         The Chunk Length must always be even. If the length of a Chunk
         Data is odd a fill-byte is added at the end of the Chunk Data.


         5.1.4 Chunk Data

         The Chunk Data can consist of more Chunks (Subchunks) or of any
         other data that the Chunk Identifier implies.

         If the chunk contains data as well as Subchunks, the data must
         follow immediately after the Chunk Header, i.e. must come
         before any Subchunks.

         Subchunks always begin on an even file offset (this is implied
         by the requirement that the Chunk Data length is even).

         When a Subchunk is present, the parent Chunk Length is still
         the sum of  the length of the parent Chunk Header and length of
         the parent Chunk Data, which is also the sum of the parent
         Chunk Length and all the Subchunk Lengths.



         5.2 Chunk Layout with examples


         5.2.1 Simple chunk-layout



                   Chunk Header          Chunk Data



           Identifi        Length           Data
              er



             WORD           DWORD



            1    1    1    1    1    1     n Bytes
           Byt  Byt  Byt  Byt  Byt Byt
            e    e    e    e    e    e














         10.06.97     Thomas Baier <thbaier@compuserve.com>       Page 7



         Revision 0.8, 06/97         POB-SDK                           8
          ______________________________________________________________

         Example:



                   Chunk Header           Chunk
                                           Data



           Identifi        Length          Data
              er



             WORD           DWORD



            0x1234       0x00000008     0xA  0xE
                                          D    F



           0x3  0x1  0x0  0x0  0x0 0x0  0xA  0xE
            4    2    8    0    0    0    D    F





         Chunk Header:
              Identifier     =    0x1234
              Length  = 0x00000008

         Chunk Data:
              Data    = 0xAD, 0xEF
























         10.06.97     Thomas Baier <thbaier@compuserve.com>       Page 8



         Revision 0.8, 06/97         POB-SDK                           9
          ______________________________________________________________

         Example with fill-byte:



                  Chunk Header            Chunk
                                           Data



          Identifier       Length          Data



             WORD           DWORD



            0x1234       0x00000008     0xA
                                          D



          0x34  0x1  0x0  0x0  0x0 0x0  0xA  0x0
                 2    8    0    0    0    D    0



         Chunk Header:
              Identifier     =    0x1234
              Length  = 0x00000008

         Chunk Data:
              Data    = 0xAD
              Fill Byte =    0x00


























         10.06.97     Thomas Baier <thbaier@compuserve.com>       Page 9



         Revision 0.8, 06/97         POB-SDK                          10
          ______________________________________________________________

         5.2.2 Chunk-layout with child-chunk



           Parent Chunk Header               Parent Chunk Data



                                                   Child             Chil
                                                Chunk Header           d
                                                                     Chun
                                                                       k
                                                                     Data



         Identif      Length      Data Identifi         Length       Data
           ier                             er



           WORD       DWORD        n      WORD          DWORD          n
                                 Byte                                Byte
                                   s                                   s



          1   1   1   1   1   1    n     1    1   1    1    1    1     n
         Byt Byt Byt Byt Byt Byt Byte  Byt  Byt  Byt Byte Byte  Byte Byte
          e   e   e   e   e   e    s     e    e   e                    s






























         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 10



         Revision 0.8, 06/97         POB-SDK                          11
          ______________________________________________________________

         Example:



                  Parent                           Parent
               Chunk Header                      Chunk Data



                                                   Child           Child
                                               Chunk Header       ChunkDat
                                                                     a



         Identif      Length       Data  Identif      Length        Data
           ier                             ier



           WORD       DWORD                WORD        DWORD



          0x1230    0x00000010            0x1231    0x00000008



          1   1   1   1   1   1   1   1   1   1       1   1   1         1
             Byt Byt Byt Byt Byt Byt By  Byt                 Byt  Byte Byt
                                                                   1
         Byt                                 Byt Byt Byt By
                                                  1
          e   e   e   e   e   e       te  e
                                  e           e   e   e   te  e         e



         0x3 0x1 0x1 0x0 0x0     0xA
                             0x0     0x  0x3 0x1 0x0 0x0 0x  0x0  0x11 0x2
          0   2   0   0   0   0   D   EF  1   2   8   0   00  0         2





         Parent Chunk Header:
              Identifier     =    0x1230
              Length  = 0x00000010 (6 bytes Header + 10 bytes Data)

         Parent Chunk Data:
              Data    = 0xAD, 0xEF

         Child Chunk Header:
              Identifier     =    0x1231
              Length  = 0x00000008 (6 bytes Header + 2 bytes Data)

         Child Chunk Data:
              Data    = 0x11, 0x22






         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 11



         Revision 0.8, 06/97         POB-SDK                          12
          ______________________________________________________________

         5.2.3 Chunk-layout with child-chunk and fill bytes

         This looks just like the one above.

         Example:



                  Parent                           Parent
               Chunk Header                      Chunk Data



                                                  Child            Child
                                               Chunk Header        Chunk
                                                                    Data



         Identif      Length       Data  Identif      Length        Data
           ier                             ier



           WORD       DWORD                WORD       DWORD



          0x1230    0x00000010     0xAD   0x1231    0x00000008      0x11



          1   1   1   1   1       1   1   1   1   1   1   1        1   1
                         Byt Byt Byt
                              1
         Byt Byt Byt Byt                                 Byt Byt Byt  Byt
                                                              1
                                     Byt Byt Byt Byt Byt
          e   e   e   e   e   e   e   e   e   e   e   e   e   e    e   e



         0x3 0x1 0x1     0x0
                     0x0     0x0 0xA 0x0 0x3 0x1 0x0 0x0 0x0 0x0 0x1  0x0
          0   2   0   0   0   0   D   0   1   2   8   0   0   0    1   0





         Parent Chunk Header:
              Identifier     =    0x1230
              Length  = 0x00000010

         Parent Chunk Data:
              Data    = 0xAD
              Fill Byte =    0x00 at position 0x07 (next chunk has to
              start at even position)

         Child Chunk Header:
              Identifier     =    0x1231
              Length  = 0x00000008



         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 12



         Revision 0.8, 06/97         POB-SDK                          13
          ______________________________________________________________

         Child Chunk Data:
              Data    = 0x11
              Fill-byte =    0x00 at position 0x0F (Chunk Length has to
              be even)



         5.3 POB Chunk Identifiers

         POB defines the Chunk Identifiers for storing all POV-Ray
         elements. Depending on the Chunk Identifier, chunks contain
         data and/or Child Chunks.

         Every POB-file starts with the chunk identifier 0x5050. This
         chunk is mandatory for identifying POB-files. All other chunks
         are optional.


         The following table gives an overview for reserved
         Chunk Identifiers:



          Identifier      Chunk Type



          0x0000- 0x0FFF  reserved for POV-Ray related Chunks



          0x1000- 0x4FFF  POV-Ray section identifier and
                          special identifier



          0x5000- 0x5FFF  POB section identifier and other
                          stuff



          0x6000- 0x7FFF  reserved for later use



          0x8000- 0xEFFF  Modeller section identifier



          0xF000- 0xFFFF  reserved for later use










         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 13



         Revision 0.8, 06/97         POB-SDK                          14
          ______________________________________________________________

         All Chunk Identifiers (0x0000-0x5FFF) are defined in
         SAMPLE\POB_ID.H and SAMPLE\POB_ID1.H. Most POB-identifiers are
         derived form POV-Ray-tokens. Additional identifiers were
         defined for structuring the POB-files.

         The POB-file is separated into several sections. There are two
         main sections: a POV-Ray Section and a user definable section
         called Modeller Section.

         The POV-Ray Section holds data like textures, objects, cameras
         and environment stuff in several sections. All sections are
         optional. The POV-Ray section does not need to hold a complete

         scene. For example, a texture designer write a POB-File that
         contains a Material section only.

         The Modeller Section holds user-definable data. The
         Chunk Identifiers in the range 0x8000 - 0xEFFF are reserved for
         this section. Any application that supports writing POB-Files
         can use this section.

         The following table gives a short overview of the POB sections
         and their Chunk Identifiers:

              POB-File Section                                 0x5050
                   POV-Ray Section                             0x5060
                        Global Setting Section                 0x1000
                          Contains data like
                          max_trace_level
                        Global Environment Section             0x1100
                          Contains data like pigments,
                          fog, sky_sphere
                        Camera Section                         0x1200
                          Contains data like normals,
                          cameras
                        Material Section                       0x2300
                          Contains data like pigments,
                          normals, finish, halos and
                          textures
                        Object Section                         0x3000
                          Contains data like sphere, blobs
                   Modeller Section                            0x5070


















         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 14



         Revision 0.8, 06/97         POB-SDK                          15
          ______________________________________________________________

         The following table lists some important chunk identifiers with
         their values. The list is not complete. For detailed

         information please refer to Chapter 5.3. All Chunk Identifier
         are defined in SAMPLE\POB_ID.H/POB_ID1.H. Note that not all
         defined "tags_ are Chunk Identifiers.






















































         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 15



         Revision 0.8, 06/97         POB-SDK                          16
          ______________________________________________________________



         Chunk Identifier Name               Identifier
                                             Value



         Section Chunks



         POB_FILESECTION_TAG                 0x5050



         POB_POVRAYSECTION_TAG               0x5060



         POB_MODELLERSECTION_TAG             0x5070



         POB_GLOBALSECTION_TAG               0x1000



         POB_ENVIRONMENTSECTION_TAG          0x1100



         POB_CAMERASECTION_TAG               0x1200



         POB_MATERIALSECTION_TAG             0x2300



         POB_OBJECTSECTION_TAG               0x3000



         Helper Chunks



         Texture Reference Chunks



         TEXTUREREF_POB_TOKEN                0x4001








         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 16



         Revision 0.8, 06/97         POB-SDK                          17
          ______________________________________________________________



         PIGMENTREF_POB_TOKEN                0x4002



         NORMALREF_POB_TOKEN                 0x4003



         FINISHREF_POB_TOKEN                 0x4004



         HALOREF_POB_TOKEN                   0x4005



         Texture Chunks




         SIMPLETEXTURE_POB_TOKEN             0x4010



         LAYEREDTEXTURE_POB_TOKEN            0x4011



         MATERIAL_MAPTEXTURE_POB_TOKEN       0x4012



         CHECKERTEXTURE_POB_TOKEN            0x4013



         BRICKTEXTURE_POB_TOKEN              0x4014



         HEXAGONTEXTURE_POB_TOKEN            0x4015



         PATTERNTEXTURE_POB_TOKEN            0x4016



         Pigment Chunks








         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 17



         Revision 0.8, 06/97         POB-SDK                          18
          ______________________________________________________________



         SIMPLEPIGMENT_POB_TOKEN             0x4020



         CHECKERPIGMENT_POB_TOKEN            0x4021



         BRICKPIGMENT_POB_TOKEN              0x4022



         HEXAGONPIGMENT_POB_TOKEN            0x4023



         BITMAPPIGMENT_POB_TOKEN             0x4024



         PATTERNPIGMENT_POB_TOKEN            0x4025



         Normal Chunks



         SIMPLENORMAL_POB_TOKEN              0x4030



         CHECKERNORMAL_POB_TOKEN             0x4031



         BRICKNORMAL_POB_TOKEN               0x4032



         HEXAGONNORMAL_POB_TOKEN             0x4033



         BITMAPNORMAL_POB_TOKEN              0x4034



         PATTERNNORMAL_POB_TOKEN             0x4035



         Finish/Halo Chunks





         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 18



         Revision 0.8, 06/97         POB-SDK                          19
          ______________________________________________________________



         SIMPLEFINISH_POB_TOKEN              0x4040



         SIMPLEHALO_POB_TOKEN                0x4050




         5.4 POB Data Types

         The POB-file format uses Intel-style endian byte order
         (low/high byte) for storing data. SAMPLE\POB_ID1.H defines some
         useful data types.












































         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 19



         Revision 0.8, 06/97         POB-SDK                          20
          ______________________________________________________________

         The following table lists these data types:



              Type       Length in             Description
                           Bytes



          P_BYTE       1              unsigned byte



          P_WORD       2              unsigned word



          P_DWORD      4              unsigned double word



          P_DOUBLE     8              eight byte IEEE floating
                                      point number



          P_DVECTOR    3 * 8          P_DOUBLE [3]



          P_DVECTOR_U  2 * 8          P_DOUBLE [2]
          V



          P_MATRIX     4 * 4 * 8      P_DOUBLE [4][4]



          P_STR        >= 1           Pascal-style string with
                                      leading length byte. Length
                                      must be even and has a
                                      maximum of 255. P_BYTE
                                      length;
                                      P_BYTE data[len];




         P_STR is not defined as a typedef because of its variable data
         length.
         The total length of string-data must be always even.
         Total length of string-data is string-length plus 1 byte. If
         string-length is even there must be a fill byte at the end of
         string-data.





         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 20



         Revision 0.8, 06/97         POB-SDK                          21
          ______________________________________________________________

         POV_SRC\POBWRITE.C and SAMPLE\POB_RD.C provide code for
         reading/writing listed data types.


         5.4.1 The POB_FILESECTION_TAG Chunk

         This chunk identifies a POB-file.

         Mandatory Data:

              P_WORD version (POB-file version)

         Optional Subchunks:

              POB_POVRAYSECTION_TAG

              POB_MODELLERSECTION_TAG


         5.4.2 POB_POVRAYSECTION_TAG

         This chunk identifies the POV-Ray section.

         Mandatory Data:

              P_WORD version (POV-Ray version)

              P_STR comment (any comment)

         Optional Subchunks:

              POB_GLOBALSECTION_TAG

              POB_ENVIRONMENTSECTION_TAG

              POB_CAMERASECTION_TAG

              POB_MATERIALSECTION_TAG

              POB_OBJECTSECTION_TAG


         5.4.3 POB_MODELLERSECTION_TAG

         This chunk identifies the modeller section.

         Mandatory Data:

              P_WORD version ( userdefinable)

              P_STR comment (userdefinable)

         Optional Subchunks:

              Identifier 0x8000-0xEFFF are reserved for Modeller chunks.
         These chunks are user definable.




         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 21



         Revision 0.8, 06/97         POB-SDK                          22
          ______________________________________________________________

         5.4.4 POB_GLOBALSECTION_TAG

         This section holds global settings of POV-Ray.

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.5 POB_ENVIRONMENTSECTION_TAG

         This sections holds environment data.

         Mandatory Data:

              -

         Optional Subchunks:

              FOG_POB_TOKEN

              ATMOSPHERE_POB_TOKEN

              BACKGROUND_POB_TOKEN

              RAINBOW_POB_TOKEN

              SKY_SPHERE_POB_TOKEN

              SIMPLEPIGMENT_POB_TOKEN

              CHECKERPIGMENT_POB_TOKEN

              BRICKPIGMENT_POB_TOKEN

              HEXAGONPIGMENT_POB_TOKEN

              BITMAPPIGMENT_POB_TOKEN

              PATTERNPIGMENT_POB_TOKEN


         5.4.6 POB_CAMERASECTION_TAG

         This section holds all scene cameras. The first camera listed
         is treated as active camera.

         Mandatory Data:

              -

         Optional Subchunks:




         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 22



         Revision 0.8, 06/97         POB-SDK                          23
          ______________________________________________________________

              CAMERA_POB_TOKEN


         5.4.7 POB_MATERIALSECTION_TAG

         This section holds all texture stuff.

         Mandatory Data:

              -

         Optional Subchunks:

              SIMPLETEXTURE_POB_TOKEN

              LAYEREDTEXTURE_POB_TOKEN

              MATERIAL_MAPTEXTURE_POB_TOKEN

              CHECKERTEXTURE_POB_TOKEN

              BRICKTEXTURE_POB_TOKEN

              HEXAGONTEXTURE_POB_TOKEN

              PATTERNTEXTURE_POB_TOKEN

              SIMPLEPIGMENT_POB_TOKEN

              CHECKERPIGMENT_POB_TOKEN

              BRICKPIGMENT_POB_TOKEN

              HEXAGONPIGMENT_POB_TOKEN

              BITMAPPIGMENT_POB_TOKEN

              PATTERNPIGMENT_POB_TOKEN

              SIMPLENORMAL_POB_TOKEN

              CHECKERNORMAL_POB_TOKEN

              BRICKNORMAL_POB_TOKEN

              HEXAGONNORMAL_POB_TOKEN

              BITMAPNORMAL_POB_TOKEN

              PATTERNNORMAL_POB_TOKEN

              SIMPLEFINISH_POB_TOKEN

              SIMPLEHALO_POB_TOKEN






         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 23



         Revision 0.8, 06/97         POB-SDK                          24
          ______________________________________________________________

         5.4.8 POB_OBJECTSECTION_TAG

         This section holds all object stuff.

         Mandatory Data:

              -

         Optional Subchunks:

              BICUBIC_PATCH_POB_TOKEN

              BLOB_POB_TOKEN

              BOX_POB_TOKEN

              CYLINDER_POB_TOKEN

              CONE_POB_TOKEN

              UNION_POB_TOKEN

              MERGE_POB_TOKEN

              INTERSECTION_POB_TOKEN

              DIFFERENCE_POB_TOKEN

              DISC_POB_TOKEN

              JULIA_FRACTAL_POB_TOKEN

              HEIGHT_FIELD_POB_TOKEN

              LATHE_POB_TOKEN

              MESH_POB_TOKEN

              PLANE_POB_TOKEN

              POLY_POB_TOKEN

              POLYGON_POB_TOKEN

              PRISM_POB_TOKEN

              QUADRIC_POB_TOKEN

              SOR_POB_TOKEN

              SPHERE_POB_TOKEN

              SUPERELLIPSOID_POB_TOKEN

              TORUS_POB_TOKEN

              TRIANGLE_POB_TOKEN



         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 24



         Revision 0.8, 06/97         POB-SDK                          25
          ______________________________________________________________

              SMOOTH_TRIANGLE_POB_TOKEN

              TEXT_POB_TOKEN

              LIGHT_SOURCE_POB_TOKEN


         5.4.9 RAINBOW_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.10 SKY_SPHERE_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.11 FOG_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.12 ATMOSPHERE_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.13 BACKGROUND_POB_TOKEN

         Mandatory Data:

              -




         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 25



         Revision 0.8, 06/97         POB-SDK                          26
          ______________________________________________________________

         Optional Subchunks:

              -


         5.4.14 CAMERA_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.15 SIMPLETEXTURE_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.16 LAYEREDTEXTURE_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.17 MATERIAL_MAPTEXTURE_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.18 CHECKERTEXTURE_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:




         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 26



         Revision 0.8, 06/97         POB-SDK                          27
          ______________________________________________________________

              -


         5.4.19 BRICKTEXTURE_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.20 HEXAGONTEXTURE_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.21 PATTERNTEXTURE_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.22 SIMPLEPIGMENT_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.23 CHECKERPIGMENT_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -




         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 27



         Revision 0.8, 06/97         POB-SDK                          28
          ______________________________________________________________

         5.4.24 BRICKPIGMENT_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.25 HEXAGONPIGMENT_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.26 BITMAPPIGMENT_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.27 PATTERNPIGMENT_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.28 SIMPLENORMAL_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -







         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 28



         Revision 0.8, 06/97         POB-SDK                          29
          ______________________________________________________________

         5.4.29 CHECKERNORMAL_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.30 BRICKNORMAL_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.31 HEXAGONNORMAL_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.32 BITMAPNORMAL_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.33 PATTERNNORMAL_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -







         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 29



         Revision 0.8, 06/97         POB-SDK                          30
          ______________________________________________________________

         5.4.34 SIMPLEFINISH_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.35 SIMPLEHALO_POB_TOKEN

         Mandatory Data:

              -

         Optional Subchunks:

              -


         5.4.36 

         Mandatory Data:

              -

         Optional Subchunks:

              -



         5.5 Limitations of POB

         There is no support for conditionals in POB.

         There is no support for animation. POV-Ray animation via the
         clock-variable is not supported, a POB file can only store the
         scene for one single clock value.




         6 Platform Notes

         Although the POB-Specification and sample code was originally
         developed for Intel platforms, every effort has been made to
         make the POB-File format and POB-SDK platform independent.

         The POB-Reader and Writer code is platform independent except
         for the floating-point data type, which is defined to be in
         IEEE-format. If your platform uses another format you will need
         to provide a conversion to this format.





         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 30



         Revision 0.8, 06/97         POB-SDK                          31
          ______________________________________________________________

         Future versions of POB-SDK may support other floating-point-
         formats.




         7 Sample POB_RD.EXE Session

         The directory POB_SDK\SAMPLE contains a simple POB-file named
         POB_TEST.POB. The original POV-Ray source file is POB_TEST.POV.
         The scene contains a simple textured sphere with rotation.

         Now, let's examine some POB aspects by viewing POB_TEST.POB
         with a hex viewer or better, POB_RD.EXE produces a debug file
         called POB.LOG. You can generat it by typing:

              POB_RD POB_TEST.POB > OUTPUT

         POB.LOG contains a lot of useful information about your POB-
         file. Every chunk that is recognized by POB_RD.EXE is written
         in a readable form to POB.LOG. The chunk header and following
         data are dumped:

              identifi The Chunk Identifier
              er

              start:   absolute file position where the chunk starts

              end:     absolute file position where the chunk ends

              len:     length of chunk

              raw      raw dump of  all following data belonging to
              data:    that chunk. Data dump is 16 byte formatted with
                       corresponding ASCII characters

              decoded  Content of chunk data will be decoded.
              data:



         OK, let's take a view to POB.LOG:

         The first chunk written has the identifier 0x5050
         (POB_FILESECTION_TAG). This is OK, because every POB-file
         starts with 0x5050. The chunk starts at position 0x0000, and
         ends at position 0x04CE. Length of chunks is calculated from
         end minus start position.

         The POB-file chunk contains following data and Child Chunks:

              chunk 0x5050 (POB_FILESECTION_TAG)

                   P_WORD    version

                   chunk 0x5060 (POB_POVRAYSECTION_TAG)




         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 31



         Revision 0.8, 06/97         POB-SDK                          32
          ______________________________________________________________

         If you look at "decoded data_ for POB_FILESECTION_TAG, you will
         see, that only a word is decoded:

              WORD version = 0x0008 (actual version of POB)

         The chunk POB_POVRAYSECTION_TAG contains a word (POV-Ray
         version = 0x0300), a string (comment) and following
         Child Chunks.

         Lets jump to POB_OBJECTSECTION_TAG. This section holds POV-Ray
         objects like sphere, box and so forth. In this case it contains
         only a sphere (0x00EF). "Decoded data_ shows a string (name of
         object), a vector (center of sphere) and a double (radius of
         sphere). Chunk data is followed by chunk FLAGS_POB_TOKEN, chunk
         matrix and chunk TEXTUREREF_POB_TOKEN.

         Chunk TEXTUREREF_POB_TOKEN holds again data (name of texture)
         and chunk matrix (transformation matrix). Note, that texture-
         data is stored outside of object-data. Object-structures hold
         only texture reference.

         Other POV-Ray objects have similar layouts:

         Generic POV-Ray Object Layout:

              . object name

              . object specific data

              . object flags

              . object transformation

              . object texture (reference)

              . bound of object

              . clipping of object

         Now, let's jump to POB_MATERIALSECTION_TAG. This section holds
         all texture related data like pigment, normal, finish, halo and
         texture chunks. In this case, only chunk
         SIMPLEPIGMENT_POB_TOKEN, chunk SIMPLEFINISH_POB_TOKEN and chunk
         SIMPLETEXTURE_POB_TOKEN is dumped.

         Pigment-data shows a string (name) and five double (color
         rgbft) and chunk PATTERN_MOD_POB_TOKEN.

         Finish-data shows a string (name) and a lot of  words, doubles
         and one vector. Please refer to POB_RD.C for detailed
         information.

         At last, chunk SIMPLETEXTURE_POB_TOKEN  holds references to
         pigment and finish elements.

         POB_RD.C and POV-Ray-Help gives detailed information about
         internal POB-structures.



         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 32



         Revision 0.8, 06/97         POB-SDK                          33
          ______________________________________________________________

         8 Source Code Description



         8.1 POBWRITE.C:

         POBWRITE.C dumps the internal object structure of POV-Ray into
         a POB-file. The code is a little complicated. This is because
         of the different internal structures of POB and POV-Ray.

         All source code-changes in the POV-Ray source code are marked
         with "//xxx_tb_. All changes were made to transfer original
         values into POV-Rays "Frame_-structure. The "Frame_-structure
         is then dumped in POBWRITE.C.

         All objects of POV-Ray have been give an additional print()-
         routine. This routine is used by POVWRITE.C to dump the object
         data structures.

         The following description discusses some important functions.

         . The main routine of POB_WRITE.C is do_pob().

         . First, object order is reversed. This is done to keep the
           object order the same in POV-Ray-files and POB-files. Then
           for every object its do_print()-routine is called. This
           collects all textures by linking them into a texture-tree. At
           this time, no POB-output is done.

         . POB-output then starts with start_chunk(), writing the
           identification for the POB-file.

         . After this, five sections are dumped in sequence starting
           with "Global Settings_, followed by "Global Environment_,
           "Camera_, "used Textures_ and "used Objects_. Note that only
           textures and objects which are actually used in the scene are
           dumped.

         . After this data is dumped, the POB-file-chunk is finish by
           calling end_chunk().



         8.2 POB_RD.C

         POB_RD.C shows a complete example for reading POB-files.
         POB_RD.C acts as reference for the POB-specification.

         Additionally there is comfortable debug-support built in.
         Details of output can be controlled by three flags:

         . __POB_DEBUG1 dumps only chunk headers to POB.LOG

         . __POB_DEBUG2 dumps chunk headers plus decoded chunk data to
           POB.LOG





         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 33



         Revision 0.8, 06/97         POB-SDK                          34
          ______________________________________________________________

         . __POB_DEBUG3 dumps chunk headers plus decoded chunk data plus
           raw chunk data (including Child Chunks)

         Finally, POB_RD.C writes POV-Ray-code to STDOUT.

         The following description discusses some important functions.

         . The function main() starts parsing. It contains code for the
           validation of a POB-files.

         . start_chunk() then reads the first Chunk Header. If it is a
           POB-file, parsing continues by calling parse_pob_file(). This
           procedure walks through all POB-sections and writes their
           contents to STDOUT.

         . end_chunk() is called to finish reading the first chunk.

         . Each section and its contents is parsed by ist own function.
           POB_RD.C simple follows the structure of POB-format.

         . Functions to read and write each basic POB-data-type (Chapter
           5.4) are provided.

         . Some functions are passed a chunk-structure as a parameter.
           This is necessary for skipping unused data.




         9 Building POVRAY.EXE (MSDOS)

         project files:


         - unpack POV30DS.ZIP

         (please obtain it from
         http://ourworld.compuserve.com/homepages/thbaier)

         - copy all contents of POV_SRC to POV-Ray source directory

         - modify the existing makefile by adding these files:

              - POBWRITE.C

              - POB_TOK.C



         If you want to recompile POV-Ray on other platforms than Intel
         please refer to Chapter 0.









         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 34



         Revision 0.8, 06/97         POB-SDK                          35
          ______________________________________________________________

         10 Building POB_RD.EXE (MSDOS)

         project files:


         - POB_RD.C

         - POB_ID.C

         - POB_ID1.C

         - (POB_ID.H)

         - (POB_ID1.H)

         For other platforms than Intel please refer to Chapter 6.




         11 Developing a POB Writer

         To write your own POB writer you need to add POB_ID.C/H and
         POB_ID1.C/H to your project. The actual code to dump objects to
         a POB-file depends on your own internal object-data-structure.
         POBWRITE.C provides some simple procedures (write_dword(),
         start_tag() ...) that you may want to use as a starting point.




         12 Developing a POB Reader

         Modify the sample reader code to read the contents of a POB-
         file into your own internal data object structure.




         13 System Requirements

         To compile the modified POVRAY.EXE (MSDOS):

              Watcom C-Compiler V10.5

         To compile POB_RD.EXE (MSDOS):

              Borland BCC3.1 or every ANSI-C-Compiler




         14 Copyright

         Please refer to LEGAL.TXT found at POB_SDK\DOC





         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 35



         Revision 0.8, 06/97         POB-SDK                          36
          ______________________________________________________________

         15 Acknowledgements

         . Thanks to Lutz Kretzschmar (Author of MORAY and Member of
           POV-Team),  who made important corrections and improvements
           to the POB-SDK.























































         10.06.97     Thomas Baier <thbaier@compuserve.com>      Page 36

