GUIDE Playstation OS and registers

Discussion in 'Sony Programming and Development' started by ASSEMbler, Jun 1, 2006.

  1. ASSEMbler

    ASSEMbler Administrator Staff Member

    Joined:
    Mar 13, 2004
    Messages:
    19,394
    Likes Received:
    1,054
    This is just a pdf rip, but it's good for quick reference for those without
    extensive resources.
    -------------------------------------------------------------

    foreword


    This document explains the mechanics of the
    target box operating system, and the concepts
    it implements.



    1.1 What is <PS-X OS> 2
    1.2 Characteristics of <PS-X OS> 3
    CHAPTER 2 <PS-X OS> in Reality 5


    2.1 Starting and operating the OS 6
    2.2 File System 8
    2.3 Memory management 9
    2.4 System tables (ToT) 11
    2.5 R3000 Registers 12


    CHAPTER 3 <PS-X OS> Service 15
    3.1 <PS-X OS> Service 16
    3.2 Application interfaces (API) 17
    CHAPTER 4 Programming Tips 19


    4.1 Use in single task mode 20
    4.2 Prohibition of interrupts 21
    4.3 Overlay processing 22
    4.4 Character string display 23
    4.5 Storage of game data 24
    4.6 Acceleration of execution speed 25
    4.7 Heap memory 26
    4.8 Program entry point 27
    4.9 Vertical blanking period detection 28
    4.10 Standard input/output 29
    4.11 CD-ROM simulator 30
    4.12 Settings necessary when activating a program 31


    CHAPTER 5 File Formats 33


    5.1 Types of Graphics data 34
    5.2 Animation data (TOD format) 35
    5.3 Modeling data (TMD format) 46
    5.4 Screen image data (TIM format) 58
    5.5 BG map data (BGD format) 63
    5.6 Cell data (CEL format) 66
    5.7 Information data (ANM format) 70


    APPENDIX A Controller Pad (DTL-H500C) Button Layout 75
    APPENDIX B Controller Pad (Final Specification) Button Layout 77




    chapter 1
    A flexible and powerful operating system is part
    of the PS-X. By using this operating system, you
    may maximize the capabilities of the PS-X.





    1.1


    What is <PS-X OS>
    <PS-X OS> was developed for the R3000, the CPU of PS-X. The efficiency of program development is
    very dependent on the environment and services that the operating system in a machine provides. If it
    has a fast enough CPU and peripheral devices, there is no need to take time to figure out a method of
    maximizing the capabilities of the hardware and one may concentrate on programming by skillfully
    using the services provided by the OS.
    The design concept of the <PS-X OS> lies in providing an environment for the developer of game
    programs and for enabling you to control programs with interrupts more easily. Based on this concept
    the kernel of the <PS-X OS> is provided as the aggregate of the services (subroutines) controlling the
    R3000 and the PS-X hardware.
    In addition each service is provided as a C language function. By using C, not only may we aim for
    better source code readability and maintainability, it also makes block structure description and
    function calls easier and makes it possible to program with greater ease.



    There are many characteristics of <PS-X OS> which implement its concept of computing.
    Programming with C
    For control of the R3000 CPU, control of the PS-X hardware units etc., all services are provided as C
    language functions. Thus, programming may be performed throughout in C.
    Easy access to the features of the R3000
    Though the interrupt processing procedures in the R3000 are said to be complex, the operating system
    under the <PS-X OS> makes use of a substitute "dispatcher" system and provides a simple interface. Of
    course the overhead that accompanies the dispatcher is kept very low. In addition, in ordinary
    operating systems the low level implementation details are not disclosed. In this way, operating system
    chip capabilities are maximized and a higher level of tuning may be achieved. Of course because
    everything can be done in C, there is no need to learn the intricacies of R3000 assembler.
    Light volume, small scale, emphasis on performance
    If the operating system is slow in speed it could ruin a speedy game program. In order to place
    emphasis on performance of applications, the size in RAM of <PS-X OS> has been kept to a maximum of
    64 Kilobytes, and it was also designed so that the CPU occupied time is minimized. In addition the OS
    system tables have been disclosed and consideration has been given to expansion of the operating
    system and acquisition of internal data.
    Furthermore, in the <PS-X OS> operating system, checks of prohibited items seen in other operating
    systems have been eliminated in order to aim for greater speed. These checks should be performed by
    the application. Thus, though there is the danger that essentially prohibited operations will end up being
    performed, cautious programming makes possible higher level tuning .
    Until now in hardware control of consoles, one had to analyze hardware driver code and painstakingly
    work through everything with an assembler. In order to lighten this burden all hardware features are
    provided as C language functions by the <PS-X OS>. The overhead of each function is kept to a
    minimum.
    Single task or multi-tasking
    The <PS-X OS> is basically a multi-tasking operating system that can perform multiple processing
    asynchronously. Multi-task control is appropriate for controlling a CD-ROM, a comparatively slow
    device, or things like playing background music.

    In addition, we have made it possible to select multi-tasking mode as an option for those who are
    accustomed to traditional programming, in other words, those who are used to single task. Immediately
    after starting the OS it is single task mode, and it is possible to select operating mode by making a
    selection at this point.




    1.2






    Characteristics of <PS-X OS> (cont.)


    Device driver based file system
    The file system (i.e. files of data on CD-ROM) in <PS-X OS> is accessed via a device driver. This allows
    multiple file systems to co-exist and increases development time by avoiding low level file manipulation
    problems.



    4





    chapter

    What sort of structure does <PS-X OS> actually
    have? In this chapter we shall explain how to start
    the OS, the memory map, and other things that one
    must know when using this operating system.







    Starting and operating the OS
    <PS-X OS> is an operating system that provides an "environment for game program developers." Thus,
    it is basically not outfitted with an interface for the user to operate hardware directly (except for the
    debug monitor in the debugging environment). It is necessary for the application to provide the user
    interface.
    Starting the Operating System
    There are two start modes with the <PS-X OS> operating system. The mode is determined by the dip
    switches of the target box and is changed when the target box is turned on or reset. Please refer to the
    "Hardware Guide" for setting the dip switches.
    Hardware mode
    This is the mode which corresponds to booting the actual PS-X hardware.
    Application boot
    First jumps to a specific address in ROM and performs a check of the hardware connected (CD-ROM
    drive etc.).
    Next, makes a decision on type of disk in the CD-ROM drive. If the disk is the appropriate one, it
    retrieves a system designation file "system.cnf" and executes this.
    If there is no disk it goes into a looping demonstration.
    Booting in a PC/AT compatible development environment
    When the dipswitch is set so that the system may be booted from a developer host (PC/AT compatible
    machine), the kernel is set in the default configuration (please refer to "library reference") and then the
    remote debugger is started. The reading and execution of the execute file which corresponds to the
    final stage of the boot sequence is performed manually. The kernel configuration cannot be altered.





    System designation file SYSTEM.CNF
    Here the PS-X system settings, and the applications that will be started are described.
    The parameters are described from the beginning of a line in "<key word> = <content>" format.
    Description is all done in 1 byte upper case alphanumeric characters and a space is necessary on both
    sides of the equal sign. Lower case characters may not be used. When the same parameter reoccurs in a
    file the first version found takes precedence. The following are the parameters that may be described.
    Table 1 System Designation File Keyword List
    Keyword Content
    BOOT
    Specify the file name to be started. The default is GAME.PSX.
    Example: BOOT=PSXAPP.EXE
    TCB
    Specify the number of tasks. The default is 4.
    Example: TCB=5
    EVENT
    Specify the number of events. The default is 16.
    Example: EVENT=5
    STACK
    The stack pointer value when the file specified by BOOT is started.
    Default is 0x8001 FF00.
    Example: STACK=800FFF0

    Debug mode
    This is a mode which is valid in the debug environment, in other words only with the target box. There are
    the following three applications in debug mode.
    Debug monitor
    The command interpreter which takes an external RS-232C channel as a standard input/output device
    and starts. Debugging is possible, using printf( ), whose output is piped through the RS-232C link.
    SCSI monitor
    SCSI channel 0 is a CPU device, and may be used for execution of remote commands from a host,
    debugging at C source level, as a DOS device driver and for file transfers.



    In the PS-X, CD-ROM is used as the application supply medium. That is to say, the file system of the
    <PS-X OS> takes as a premise that files are on CD-ROM.
    The file system of PS-X is based on ISO 9660 level 1 which is an international standard.
    File name conventions
    File names take the format of "<BASENAME><EXT>." The <BASENAME> is eight 1 byte alphanumeric
    characters and the <EXT> is 3 alphanumeric characters. 1 byte katakana and 2 byte Chinese
    characters (kanji) cannot be used. <BASENAME> and <EXT> are separated by a period. This is the
    same name format as used in MS-DOS.
    Subdirectories
    Subdirectories cannot be created. Files are all arranged in the root directory.
    Number of Files
    There is no limit on the number of files that may be placed in the root directory.



    Using memory space on the R3000 is important when using <PS-X OS>. Here we shall explain the
    memory management of the <PS-X OS>, focusing on the memory map.
    Memory Map
    We will explain the memory map of <PS-X OS>.
    To begin with, we call the space that a program uses "logic space." Logic space is expressed by a 32 bit
    address, and is mapped on physical space in multi layer. In C language it is accessed with a long
    pointer.

    Logic memory Physical memory
    Fig. 2-1 Logic memory/physical memory allocation
    "Physical space" is an address in the installed memory device (i.e. an address on the actual memory
    chip). If a logic space address is accessed that is not mapped in physical space, a "bus error" will be
    generated.
    Interface registers with peripheral devices are also mapped in logic space (i.e. memory mapped I/O).
    Memory devices may be accessed with 1 to 4 byte units but accessing the interface register is done by a
    method that uses specific size units. When accessed by units other than this a bus error will be
    generated.


    2.3


    Memory management (cont.)
    Table 2 Memory Map
    I Cache
    The validity/ invalidity of the Instruction Cache (hereafter I cache) is determined by the 4 upper bits of
    the logic space. With the segments which correspond to the memory devices mentioned earlier I cache is
    valid for A, B, P and Q, but is invalid with C and R. Segments, in the R3000 refer to block units
    separating memory space from features and differ in this respect from other CPU's (8086 type) so
    please be careful.
    When I cache is valid, machine code is read into I cache in a block. If the desired instruction is in I
    cache, main memory does not need to be accessed via the bus. Speed of execution of applications is
    improved.
    The I cache is packaged with 1K words (4 kilobytes), and one way mapped. In other words, logic space is
    divided into 4 kilobyte units, and these units are mapped onto the I cache.
    D cache
    The D cache is configured by the high speed memory loaded in the CPU. Internally it is structured as a
    scratch pad and is mapped in the memory space as S segment so that "game program developers" can
    access it.
    Both data and programs may be placed in this segment. However it cannot be the target of a DMA
    transfer.



    In order to uniformly access each type of system table used internally in the operating system, system
    table information is disclosed as the structure ToT (Table of Tables). ToT is placed at address
    0x00000100.
    The contents of ToT are as follows.
    Table 3 System tables
    Entries
    Nature
    0 Queue header requires interrupt processing
    1 Task state queue header
    2 Task management block
    3 System reserved
    4 Event management block
    5~31 System reserved
    Definition of ToT data structure
    The ToT data structure is described by the following C structure.
    The structure is defined in the header file include/kernel.h.
    struct ToT { /*system table tab le*/
    unsigned long *head; /*system table lead address*/
    long size; /*system table size (byte)*/
    };



    Here we shall explain the R3000 registers. For higher level programming knowledge of the R3000
    registers is necessary but in normal C programming there is no need to be especially conscious of it.
    The R3000 registers may be divided into "General purpose registers" and a "Program counter."
    General Purpose registers
    There are 32, 32 bit general purpose registers. Each register is assigned to the following specific uses by
    the compiler. When using a threaded data base and developing with an assembler, it is necessary to use
    the registers in the following way.
    Table 4 R3000 General Purpose Registers
    Macro (1)
    Macro (2)
    Assignment
    R_ZERO
    R_R0
    0 fixed
    R_AT
    R_R1
    Assembler reserves
    R_V0
    R_R2
    Return value
    R_V1
    R_R3
    Return value (for double type)
    R_A0
    R_R4
    Argument #1
    R_A1
    R_R5
    Argument #2
    R_A2
    R_R6
    Argument #3
    R_A3
    R_R7
    Argument #4
    R_T0
    R_R8
    Temporaries
    R_T1
    R_T2
    R_R9
    R_R10

    R_T3
    R_R11

    R_T4
    R_R12

    R_T5
    R_R13

    R_T6
    R_R14

    R_T7
    R_R15
    Saved temporaries
    R_S0
    R_R16
    ""
    R_S1
    R_R17

    R_S2
    R_R18

    R_S3
    R_R19

    R_S4
    R_R20

    R_S5
    R_R21

    R_S6
    R_R22

    R_S7
    R_R23

    R_T8
    R_R24
    Temporaries
    R_T9
    R_R25
    ""
    R_K0
    R_R26
    Kernel reserve #0
    R_K1
    R_R27
    Kernel reserve#2
    R_GP
    R_R28
    Global Pointer
    R_SP
    R_R29
    Stack Pointer
    R_FP
    R_R30
    Frame pointer
    R_RA
    R_R31
    Return previous address




    Precautions to be taken when using the general purpose registers are as follows:
    AT register
    The assembler uses the AT register as a work area. The C compiler and assembler program are
    prohibited from using this register.
    Return address
    The R3000 does not have a subroutine call concept. Therefore, this is substituted by a jump command
    saving the return address in a register. The assembler may specify the register where it is saved but the
    compiler is restricted to the RA register.
    C Language function arguments
    When there are less than 4 arguments they are stored in A0 to A3 registers in order from the left. When
    there are more than 4 arguments they are accumulated on the stack. Space for 4 arguments is allocated
    on the stack, but is dummy. The remaining arguments are passed on the stack; the first 4 are in
    registers as usual.
    C Language Function Return Value
    The return value of a function is stored in the V0 register when less than 32 bits. When 64 bits (double)
    the 32 high order bits are stored in the V1 register.
    Stack
    There is no stack concept in the R3000. Therefore, the compiler stores the pointer in the SP register
    and implements a stack. In order to efficiently use a function frame (a memory area for automatic
    variables and a work area) it stores "the lead address of the frame for that function" in the FP register.
    This value is determined initially by SP. When the module is started, FP is set to SP.
    Global pointer
    The R3000 memory is accessed by "encoded 16 bit offset register indirect mode." In order to effectively
    accomplish this, the compiler consolidates the variables up to 64 Kilobytes in a "bss section" block.
    Here the block's start address is stored in the GP register and using the above mode access is
    performed by one word. This address value is called a "global pointer" and it does not vary in the
    module.
    Program counter
    The program counter cannot be accessed directly. The actions of the program counter are as follows.



    2.5


    R3000 Registers (cont.)
    Immediately after power-on reset
    The program counter will be 0xbfc00000.
    When there is an external interrupt and when an error (except a debug error) occurs
    1) The content of the program counter will be saved to the EPC register of coprocessor 0 (the
    section which handles errors and interrupts in the R3000).
    2) The processor jumps to 0x00000080.



    chapter

    The most significant characteristic of <PS-X OS>
    is that all features controlling the R3000 and PS-
    X hardware are provided as C functions. Because
    of this, the burden on the program developer is
    lightened, he or she may proceed with development
    more efficiently.








    3.1


    <PS-X OS> Service

    The services provided by <PS-X OS> are called application programmer interfaces (API). The programs
    which call the OS must have their function libraries linked. All of the PS-X features are covered by the API.
    Program readability will increase if only API calls are used.


    16




    A general service for controlling PS-X hardware including the CPU. All of the PS-X features are covered by
    the API.
    The API has the following services. Please refer to "library reference" concerning functions provided by the
    API, and details about data structures.
    Module management service
    Module management is a basic service which loads and executes user application programs.
    Event management service
    Event management is a service controlling program execution triggered by asynchronously occurring
    events.
    Controller service
    This is a service which deals with the controller which is the PS-X 's chief input device. It supports up to 64
    controllers which are configured with a maximum of 16 buttons.
    I/O management service
    This is a service which supports low level input/output to files and logic devices. All file control in PS-X is
    performed using this service.
    Thread management service
    "Threads" are aggregates of resources necessary for executing programs. Specifically they are
    composed of register states, stack areas and CPU states. Multiple threads, multi-tasking and multi-
    interrupts can be implemented using thread management.
    Other services
    There are various other services, for example, setting up the I cache and the R3000 etc., and
    authorizing or prohibiting processing of interrupts.
    Standard C library
    Provides standard C functions based on K & R such as character string operations, standard input and
    outputs.
    Root counter management service
    Provides a counting feature which is used by game programmers for time restrictions and timing
    adjustments.



    3.2


    Application interfaces (API) (cont.)
    A "Root counter" causes automatic count timing. There are 4 elements to this.
    (a) Display pixels
    (b) Horizontal synchronization
    (c) System clock
    (d) Vertical synchronization
    In all of these counters except (d) a 16 bit target value can be set.
    Counters count from zero and when they reach the target value generate an interrupt, then
    automatically clear to zero and begin counting again. The target value of (d) is fixed at 1.
    PS-X library
    This is a group of C functions which are for controlling expression features like graphics and sound. It
    provides the following library files. Please refer to "library reference" for details.
    Table 5 Types of library Files
    Name of library Feature
    File Format
    This defines the internal structure of the files that the PS-X library processes. PS-X special tools also
    generate and process files in this format. Details are explained in Chapter 5.




    chapter 4
    In this chapter we will cover precautions to be
    taken and tips when programming with <PS-X OS>.






    4.1


    Use in single task mode

    <PS-X OS> is basically a multi-tasking operating system which starts out in single task mode. If the
    "game program developer" does not start multiple threads it will operate in single task mode. One does
    not necessarily have to use the multi-tasking feature.


    20




    By calling the EnterCritical Section( ) function, interrupts can be stopped. Authorization is performed by
    EnterCritical Section( ).



    4.3


    Overlay processing

    Overlay processing in the PS-X program takes the form of executing a child process from a resident
    module.

    The operating system drives the hardware and starts the file to be executed, but in overlay processing it
    is necessary for the application to do this.


    22




    There is no character generator and fonts are not provided in PS-X. To display character strings the
    application must provide data and must perform this as part of a graphics operation.



    4.5


    Storage of game data

    A special PS-X back up cartridge is provided as a game data storage device. Since special functions
    are also provided for the cartridge, this may be used during programming.


    24




    Here we shall provided a number of tips for increasing the speed of execution of applications.
    File partition and placement
    By partitioning files into appropriate sizes and placing them carefully on the CD-ROM, the speed of
    starting and reading of data can be increased.
    Using the I cache
    Of the segments that correspond to the memory devices described in Chapter 2, I cache is valid with A, B,
    P and Q and is invalid with C and R. Since the size of I cache is 4 kilobytes, it is very important where
    and how code is placed. Careful placement of code can result in increased speed.
    Using the S segment
    Using the S segment that is part of the CPU's high speed memory is another factor in increasing speed.



    4.7


    Heap memory

    The C language heap memory management function group is provided as one part of the C library but
    <PS-X OS> does not do the initialization necessary for its use. That is because the "game program
    developer" must manage all memory available.

    When using the heap memory management functions, first execute the heap memory initialization
    functions belonging to "other services" and then specify the start address and size of the heap memory.


    26




    The first program started in running PS-X is prepared as an execute file. The file name may be specified
    following the boot sequence (Please refer to the "Hardware Guide"). The first address to be executed of
    the execute file, in other words, the entry point, may be specified by a function name at link time. When
    not specified, main( ) will be selected (C language default). The function that will be the entry point
    cannot be given an argument.


    4.9


    Vertical blanking period detection
    If the root counter and the event management service are used, the beginning of the vertical blanking
    period can be detected. The beginning of the vertical blank acts as a trigger so that polling, calling of
    queue functions and starting of handler functions can be performed. Call queuing functions in the
    following way:
    Sam ple()
    {
    unsigned long EV;
    Enter Cr it i cal Sect ion ();
    EV = Open Event (RCntCNT3, EvSpI NT, EvMdNOI NTR, NULL);
    EnableEvent (EV);
    SetRCnt (RCntCNT3, 1, RCntMdINTR);
    StartRCnt (RCntCNT3);
    ........
    / * Initialization of controller * /
    ........
    while (1){
    WaitEvent (EV);
    ........
    }
    }



    Immediately after starting, standard output is allocated to file descriptor 0 and standard input to file
    descriptor 1. The input output device is RS232C channel 0 (device name "tty00"). Input output functions
    such as printf( ) and getchar( ) may be used. The circuit designation of this port is 8 bit characters, 1 stop
    bit, no parity, hardware flow control. Control with PC/AT can be performed with the special cable
    packaged together with the target box. A 25 pin type host may be connected by cable.



    .11


    CD-ROM simulator

    The "CD-ROM simulator" feature which uses the developer host file system is provided as one aspect of
    the development environment. Please refer to "Psy-Q Development Environment."


    30



    In addition to designating a starting address, in other words the program counter initial value, a stack
    pointer (SP) value should be set. When executing a program and a value corresponding to an address
    that cannot be accessed is in the stack pointer a "bus error" will be generated.





    chapter

    Here we explain graphics data file formats that
    are processed by the PS-X library. Data is
    created with a special PS-X tool.








    There are 2 types of PS-X graphics, 3 dimensional graphics which characterize this system and the 2
    dimensional graphics.
    In 3 dimensional data, there are "modeling data (TMD)" which express the shape and surface attributes of
    an object and "animation data (TOD)" which includes information on object placement.
    In 2 dimensional data, in addition to "image data (TIM)," which are sprite patterns and texture materials,
    there are "BG map data (BGD)" for BG screen map data and sprite animation, "cell data (CEL)," and
    "information data (ANM)."
    We shall explain each type of data in order below.
    Modelling data
    Modelling tool
    Material editor


    34




    TOD format is for describing a 3 dimensional object through time and it corresponds to functions in the
    expanded graphics library "libgs."
    Specifically, it describes for each frame the data for a three dimensional object which appears, changes or disappears in a 3
    dimensional animation and arranges data for each frame following the flow of time.
    File Format
    TOD files consist of file header and frame data as follows:
    MSB LSB
    31 0


    32 bit
    resolution
    version
    number of frames
    Frame 1
    Frame 2
    Frame 3
    Frame 4
    Frame 5
    file ID





















    : :
    Fig. 5-2-1 TOD file format
    Header
    At the beginning of TOD files there is a 2 word (64 bit) header. The following four types of information
    are described in headers.
    file ID (8 bits)
    This indicates that it is an animation file. Value is 0x50.
    version ( 8 bits)
    This indicates the version of the animation. Value begins from 0x00.
    resolution (16 bits)
    This is the time that one frame is displayed (unit tick = 1/60 second).




    Animation data (TOD format) (cont.)




    (d) number of frames (32 bits)
    The number of frames described in the file.
    Frame
    Following the header the frame is described. Frames are arranged chronologically
    (See Figure 5-2-2).
    Frame Section
    Each frame is composed of a frame header and a succeeding packet as follows.
    MSB LSB
    31 0
    32 bit
    number of packets frame size

    frame number

    packet header

    packet data

    . .
    . .

    packet header

    packet data


    Fig. 5-2-2 Vertex structure
    Frame header
    There is a 2 word frame header at the beginning of each frame. The following information is
    described in a frame header.
    frame size (16 bits)
    Frame length (including header) in words.
    number of packets (16 bits) Number of packets.


    frame numbers (32 bits) Frame
    number.
    PACKET
    After a frame header there is a packet. Each packet consists of a 1 word packet header at the
    beginning followed by packet data. (See Figure 5-3) There are various things in a packet.


    5.2



    The size of packet data in each packet will not be the same whether the packets are of the same
    type or not.
    Packet section
    Packets are composed of packet headers and packet data as follows:
    MSB LSB
    31 0


    32 bit
    packet length
    flag
    packet type
    object ID


    packet data




    Fig. 5-3 Packet format
    Packet header
    The following information is described in a packet header.
    (a) Object ID (16 bits)
    The identification of the object concerned.
    Packet type (4 bits) Type of
    packet data.
    Flag (4 bits)
    Meaning differs with packet.
    Packet length (8 bits)
    Packet length (including header) word (4 bytes) unit size.
    An "object" is a 3 dimensional object (GsDOBJ) handled by libgs (expanded indicates the
    object that will reflect the packet data.
    In packet type the type of data stored in packet data is stored. The meaning of flag will differ
    according to this packet type.


    Packet length expresses packet length in word (4 bytes) units.

    Packet data
    Various types of data such as the GS COORDINATE structure, RST value and TMD data
    identification (modeling ID) etc. are stored in packet data.

    The type of a packet is indicated by the packet type in the header. The relationship between the
    packet type value and the type of data is as follows:





    Animation data (TOD format) (cont.)




    Table 6 Packet type value and nature of packet data
    0 Attribute
    1 Coordinate (RST)
    10 TMD data ID
    11 Parent object ID
    100 Matrix value
    101 TMD data body
    110 Light source
    111 Camera
    1000 Object control
    1001~1101 (User defined)
    1110 (System reserved)
    1111 Special commands
    In the following we explain data types.
    Packet data - attribute
    When packet type is 0000, the data that designates attribute of the GsDOBJ structure in the packet
    data is stored. In this case a flag is not used.
    Packet data is composed of 2 words as follows:
    MSB




    31302928
    •

    • •




    8
    7
    6
    5
    4
    3
    2
    1



    0


    31302928
    •

    • •




    8
    7
    6
    5
    4
    3
    2
    1



    0




    Fig. 5-4 packet data configuration when attribute
    The first word is a mask which indicates the section which changes value and the section which does not
    change value. 0 is set in the bit which corresponds to the item which will change and 1 is set in the bit for
    the value which will not change.
    In the second word, new data is entered in the bit which corresponds to the item which will change. Set
    other bits at 0.
    Here be careful to set the default value for the bit which will not change so that the first word will be 1 and
    the second word will be 0 so that the first word and second word will be different.





    The meaning of each bit in the packet data of the second word of Fig. 5-4 is as follows:
    Table 7 The meaning of each bit in packet data
    Bit (0) - Bit (2)
    material decrease
    00: material decrease 0
    01: material decrease 1
    02: material decrease 2
    03: material decrease 3
    Bit (3)
    Number 1 lighting mode
    0: fog off (no fog)
    1: fog on (fog)
    Bit (4)
    Number 2 lighting mode
    0: material on (material)
    1: material off (no material)
    Bit (5)
    Number 3 lighting mode
    0: use lighting mode
    1: use default lighting mode
    Bit (6)
    Light source
    0: No lighting calculation
    1: Lighting calculation restriction ON
    Bit (7)
    Action when overflow
    0: z overflow clip
    1: z overflow not clip
    Bit (8)
    Existence or non-existence of back clip
    0: Valid
    1: Invalid
    Bit (9) - Bit (27)
    System reserved (initialised at 0)
    Bit (28) - Bit (29)
    Translucence rate
    00: 50%
    01: Add 100%
    02: Add 50%
    03: Add 25%
    Bit (30)
    Translucence
    0: OFF
    1: ON
    Bit (31)
    Display
    0: Display
    1: Nondisplay

    For example, when "light source computation ON," packet data will be as shown in Fig. 5-5.
    In the first word, bit (6) specify 0 to indicate that light source will change, and specify 1 to indicate no
    change. Thus, the first word will be 0xffbf.
    In the second word, set 1 in bit (6) which indicates "light source computation ON" and in other bits
    whose values do not change set the default, 0. Thus the second word will be 0x0040.


    Animation data (TOD format) (cont.)





    Fig. 5-5 Packet data when Illumination calculation restriction is ON
    Packet data - Coordinate (RST)
    translation scaling rotation matrix type
    Fig. 5-6 Flag when Coordinate (RST)
    Table 8 Meanings and values of items in Fig 5-6
    matrix type
    RST matrix type
    0: Absolute value
    1: Differential matrix from preceding frame
    rotation
    Rotation (R) flag
    0: None
    1: Has
    scaling
    Screening (S) flag
    0: None
    1: Has
    translation
    Parallel movement (T) flag
    0: None
    1: Has

    When packet type is 0001, data that sets the coord of the GsDOBJ structure is stored in packet data. In
    this case the flag will have the following meaning.
    The configuration of packet data will differ according to the values of the flag rotation bit, the scaling bit,
    and the translation bit as per Fig. 5-7.
    In Figure 5-7, Rx, Ry, and Rz express the X axis component, the Y axis component and the Z axis
    component of the turning angle, respectively.
    In the same way Sx, Sy, and Sz express the X axis component, the Y axis component and the Z axis
    component of scaling, and Tx, Ty, and Tz express the X axis component, the Y axis component and the Z
    axis component of parallel movement, respectively.


    5.2



    (a) flag: 1110 or 1111
    Rx Ry
    Rz
    Sy
    * * ** * *
    Tx
    Ty
    Tz
    (c) flag: 1010 or 1011
    Rx Ry
    Rz Tx
    Ty Tz
    (e) flag: 0010 or 0011
    Rx Ry
    Rz
    (g) flag: 1000 or 1001
    Tx Ty
    Tz




    Sx

    Sx

    Sz



    Sz








    (d) flag: 1100 or 1101
    Sy

    ******
    Tx
    Ty
    Tz
    (f) flag: 0100 or 0101 Sy

    ******




    Sx Sz







    Sx Sz








    Fig. 5-7 Packet Data configuration when Coordinate (RST)
    Packet data - TMD data ID
    When packet type is 0010, the modeling data ID (TMD data) of the real object is stored in the packet
    data (See Figure 5-8). The TMD data ID is composed of 2 bytes. In this case no flag is used.
    16 bit

    * ** * ** ** * *
    TMD data ID

    Figure 5-8 Packet data configuration when TMD data ID
    Packet data- parent object ID
    When packet type is 0011, the parent object ID of the object specified is stored in packet data (See
    Figure 5-9). The parent object ID is composed of 2 bytes. In this case no flag is used.


    Animation data (TOD format) (cont.)
    Packet data - MATRIX value
    When the packet type is 0100, the data which designates coord members of the GsCOORDINATE2
    structure to which GsDOBJ2 structure points is stored in packet data. In this case a flag is not used.
    16 bit

    ********** Parent object ID

    Fig. 5-9 Packet data configuration when Parent object
    The configuration of packet data is as follows:
    Packet data - TMD data body
    When packet type is 0101, TMD data is stored. Not presently supported.
    R01
    R00
    R10
    R02
    R11
    R11
    R21
    R20
    **********
    R22
    Tx
    Ty
    Tz

    Fig. 5-10 Packet data configuration when matrix value
    Packet data - light source
    When packet type is 0110, the data that designates light source is stored in packet data.
    When this is the case, the object ID is separate from the normal object ID and becomes the light source ID.
    Flags have the following meanings.
    ********** colour direction data type
    Fig. 5-11 Flag when light source packet


    5.2



    Table 9 The meanings and values of the items in Fig 5-11
    data type
    Data type
    0: Absolute value
    1: Difference from preceding frame
    direction
    Direction flag
    0: None
    1: Has
    color
    Color flag
    0: None
    1: Has

    The configuration of packet data will differ with the value of the flag direction bit, and the color bit as
    follows:
    (a) flag: 0110 or 0111 (b) flag: 0100 or 0101


    X
    Y
    Z
    **
    B
    G
    R

    (c) flag: 0010 or 0011
    ** B G R
    Fig. 5-12 Packet data when light source packet
    Packet data - camera
    When packet type is 0111, data which designates viewpoint location information is stored in the packet.
    When this is the case, the object ID is separate from the normal object ID and becomes the camera ID.
    Flags have the meaning indicated in Figure 5-13. Please be careful to note that the meaning of other bits
    will change depending on the type bit.
    (a) camera type: 0
    z angle position & data type camera type
    reference = 0
    (a) camera type: 1
    translation rotation data type camera type =
    1

    Fig. 5-13 Flag for camera





    Animation data (TOD format) (cont.)




    When camera type bit is 0 other bits are:
    Table 10 Other bits when the camera type bit is 0
    data type
    Data type
    0: Absolute value
    1: Difference from preceding frame
    position & reference
    Position and reference position flag
    0: None
    1: Has
    z angle
    Reference angle flag from level
    0: None
    1: Has

    When camera type bit is 1 other bits are:
    Table 11 Other bits when the camera type bit is 1
    data type
    Data type
    0: Absolute value
    1: Difference from preceding frame
    rotation
    Rotation (R) flag
    0: None
    1: Has
    translation
    Horizontal movement (T) flag
    0: None
    1: Has

    The configuration of packet data changes depending on the flag as in Figures 5-14 and 5-15.


    (a) flag: 1100 or 1110
    Px
    Py
    Pz
    Rx
    Ry
    Rz
    Z
    (c) flag: 1000 or 1010


    (b) flag: 0100 or 0110
    Px
    Py
    Pz
    Rx
    Ry
    Rz



    Z
    Fig. 5-14 Number 1 Packet data configuration for camera



    5.2
    (a) flag: 0111 (b) flag: 0011




    Rx
    Ry
    Rz
    Tx
    Ty
    Tz tz
    (c) flag: 0101
    Tx
    Ty
    Tz
    Fig. 5-15 Number 2 Packet data configuration for camera
    Object control
    When packet type is 1000, this designates control for the object. When this is the case, there is no
    packet data. Flags will have the following meanings.
    Table 12 Flag meaning and value when object
    0
    create
    1
    kill
    0010~1111
    system reserved

    Special Commands
    When packet type is 1111, control of animation is performed. Details are not yet set.



    TMD format is a modeling data format which is compatible with the PS-X expanded graphics library.
    TMD data is downloaded to memory and may be passed as an argument to functions provided by
    libgs.
    TMD files are created by rsdlink command at the time a program is created from the RSD file (text data of a
    high degree of abstraction) created by artist's tools such as the 3D Graphics tool made by Sony.
    The data described by the TMD are primitive aggregates such as the polygons and straight lines that
    make up an object. One TMD file may hold the data for multiple objects.
    Coordinate value
    The coordinate values in TMD data follow the space handled by the PS-X system's expanded graphics
    library and the positive direction for the X axis is right, for the Y axis, down, and the Z axis the back of
    the screen. Coordinates are 16 bit coded integer values and the value that the coordinate value of each
    axis may take is -32767 to +32768.
    Because in the design stage, in other words in RSD format, the VERTEX value is a floating point, there is a
    need to expand or reduce and align the scale when going from RSD to TMD. The scale adjustment value
    at this time is included in the object structure that will be described later as a reference value (please
    refer to the section on OBJ TABLE section).
    However, this value is an index value of what scale should be used in mapping world coordinates, and at
    present this scale value is ignored by libgs.
    File format
    TMD files are configured by 4 blocks. They have 3 dimensional object tables, and 3 types of data
    entities, PRIMITIVE, VERTEX, and NORMAL which configure these.
    HEADER
    OBJ TABLE SECTION
    :
    PRIMITIVE SECTION
    :
    VERTEX SECTION
    :
    NORMAL SECTION
    :
    Fig. 5-16 TMD File Format


    5.3



    HEADER section
    The HEADER section is 3 words (12 bytes) of data which have information concerning the data structure
    and is as follows.
    ID
    FLAGS
    NOBJ
    Fig. 5-17 Header structure
    ID
    32 bit length data, expresses TMD file version.
    Present version is 0x00000041.
    FLAGS
    32 bit length data, expresses TMD data configuration information.
    Least significant bit (LSB) is FIXP bit and the remaining bits are reserved.
    Value for all is 0.
    The FIXP bit expresses whether the pointer value held by the object
    structure that will be described later is the actual address or not.
    NOBJ
    Integer that expresses the number of objects.

    OBJ TABLE section
    The OBJ TABLE section is a table in which structures with pointer information are stored. These indicate
    where the data for each object is stored. The table is configured as follows.
    OBJECT #1
    OBJECT #2
    : :
    Fig. 5-18 OBJ table structure
    Object structures are as follows:
    st ruct
    object



    {



    unsigned
    long *vert_top;

    /*VERTEX leading address*/
    unsigned
    long n_vert:

    /*VERTEX number*/
    unsigned
    long *norma
    l_top:

    /*NORMAL leading address*/
    unsigned
    long n_norma l;

    /*NORMAL number*/
    unsigned
    long *primi
    tive_top;

    /*PRIMITIVE leading address*/
    unsigned
    long n_pr imi
    tive;

    /*POLYGON number*/
    long
    scale;

    /*Scaling factor*/
    }


    5.3


    Modeling data (TMD format) (cont.)




    Of the members of the structure, the meaning of the pointer value (vert_top, normal_top, primitive_top) will
    vary with the value of the FIXP bit of the HEADER section. When FIXP is 1, it will indicate the actual
    address. When FIXP is 0 it expresses the relative address with the top of the object section as 0.
    The scaling factor is encoded in long form, and the second exponential value becomes the scale value. In
    other words, when the scaling factor is 0, it is 0, when 2 the scale value is 4, when -1, the scale value is
    1/2.
    PRIMITIVE section
    The primitive section is an arrangement of drawing packets of object primitives and one primitive is
    expressed in one packet. (See Figure 5-19).
    Primitives defined by TMD differ from the drawing primitives handled by libgpu. With TMD primitives,
    transparent conversion processing is done by libgs function and they are converted to drawing
    primitives.
    Each packet has a variable length and the size and structure vary depending on the type of primitive.
    31(MSB) 0(LSB)
    mode flag ilen olen
    packet data
    .


    Fig. 5-19 Drawing packet general structure
    Each item in Figure 5-19 is as follows:
    mode (8 bit)
    mode indicates the type of primitive and added attributes. They have the following bit structure.
    CODE: 3 bit code expressing entities
    MSB LSB





    001 = polygon (triangle, rectangle)
    010 = Straight line
    011 = Sprite
    OPTION: varies with the option bit and CODE values
    (Listed with the list of packet data configurations described later)

    Fig. 5-20 MODE


    5.3



    flag (8 bit)
    flag indicates option information when rendering and has the following bit configuration.
    MSB LSB



    FCE: When 1, two-sided polygon, when 0, one-sided polygon.
    (Only valid when the CODE value is polygon)
    LGT: When 1, no light source computation, when 0, light source computation.
    Fig. 5-21 flag
    Ilen (8 bit)
    Indicates packet data section word length.
    Olen (8 bit)
    Indicates the word length of the 2D drawing primitives that are generated by intermediate
    processing.
    Packet data
    Content varies depending on type of primitive. Please refer to "Packet data configuration" which will
    be discussed later.
    VERTEX section
    The VERTEX section is a string of structures expressing vertex. The format of the structure is as shown in
    Figure 5-22.
    MSB LSB
    VY VX
    -- VZ


    VX,VY, VZ Vertex coordinates X,Y, Z values (16 bit integers)
    Fig. 5-22 VERTEX structure




    Modeling data (TMD format) (cont.)




    NORMAL section
    The NORMAL section is a string of structures expressing a vertex normal. The format of the structure is as
    shown in Figure 5-23.
    MSB LSB
    NY NX
    -- NZ


    NX, NY, NZ: X, Y, Z elements of normal (16 bit fixed point)
    Fig. 5-23 NORMAL structure
    The values of NX, NY and NZ are signed 16 bit fixed points with 4096 treated as 1.0. (See Figure 5-24)
    bit 15 14 12 11 0

    Sign: 1 bit
    Integer section: 3 bits
    Decimal section: 12 bits
    Fig. 5-24 Fixed point format
    Packet data configuration
    There are the following in the parameters included in the packet data of the primitive section.
    Vertex (n)
    16 bit length index value pointing to VERTEX. Expresses the number element from the top of the
    VERTEX section of the object that the polygon belongs to.
    Normal (n)
    A 16 bit length index value pointing to NORMAL, like Vn.
    Un, Vn
    X and Y coordinate values in the texture source space of each vertex.

    Rn, Gn, Bn
    RGB value expressing color of polygon, an 8 bit unsigned integer value. When no light source
    computation, it is necessary to specify the calculated intensity in advance.


    5.3



    TSB
    Has information concerning texture and sprite patterns. Is as follows:
    bit 15 98765 4 0


    0000 000 0
    T
    P
    A
    B
    TPAGE

    F
    R


    TPAGE: Texture page number (0-31)
    ABR: Translucency rate (mixed ratio). Only valid when ABE is 1.
    00: 50%back + 50% polygon
    01: 100%back + 100% polygon
    10: 100%back + 50% polygon
    11: 100%back - 100% polygon
    TPF: Texture color mode
    00: 4bit CLUT 01:
    8bit CLUT 10: 15bit
    Figure 5-25 TSB format
    CBA
    Indicates the storage location of CLUT in VRAM
    31 16
    C C
    L L
    Y X

    CLY CLUT lead Y coordinate (9 bits)
    CLX CLUT lead X coordinate (6 bits)
    Fig. 5-26 CBA
    Please use the above as a reference since we describe the configuration of packet data for each type of
    primitive.
    Packet data configuration example -
    3 vertex polygon with light source calculation
    A 3 vertex polygon with light source calculation will be as follows: The mode and flag values in this
    example express a one sided polygon with translucency in the OFF state.





    Modeling data (TMD format) (cont.)




    Bit configuration of mode value
    The mode value bit configuration of the primitive section is as follows:
    mode value bit configuration
    MSB LSB

    I


    T
    A
    T

    001
    I
    1

    M
    B
    G


    P



    E
    E
    E

    IIP: Shading mode
    0: Flat shading
    1: Gouraud shading
    TME: Texture specification
    0:Off 1:On
    ABE: Translucency processing
    0:Off 1:On
    TGE: Brightness calculation at time of texture mapping
    0:On
    1 :Off (Draws texture as is)
    Fig. 5-27 Mode structure
    Packet data configuration
    Packet data configuration is as follows.


    Flat, No-Texture
    0x20
    0x00
    0x03
    0x04
    Note
    B
    G
    R
    Vertex0
    Normal0
    Vertex2
    Vertex1

    Flat, Texture
    Gouraud, No-Texture
    0x30
    0x00
    0x04
    0x06
    Note
    B
    G
    R
    Vertex0
    Normal0
    Vertex1
    Normal1
    Vertex2
    Normal2

    Gouraud, Texture





    Packet data configuration example -
    For a polygon with 3 vertices and no light source calculation
    Bit configuration of mode value
    The primitive section mode value bit configuration is as follows. For the value of each bit please
    refer to "3 vertex polygon with light source calculation."
    Mode value bit configuration
    MSB LSB

    I


    T
    A
    T

    001
    I
    0

    M
    B
    G


    P

    E

    E
    E

    Fig. 5-29 Mode byte
    Packet data configuration
    Packet date configuration will be as follows:


    Flat, No Texture
    0x21
    0x01
    0x03
    0x04
    Note
    B
    G
    R
    Vertex1
    Vertex0
    --
    Vertex2

    Flat, Texture
    0x25
    0x01
    0x06
    0x07
    CBA
    V0
    U0
    TSB
    V1
    U1
    --
    --
    V2
    U2
    --
    B
    G
    R
    Vertex1
    Vertex0
    --
    Vertex2

    Note: Has same value as mode.


    Gouraud, No Texture
    0x31
    0x01
    0x05
    0x06
    Note
    B0
    G0
    R0
    --
    B1
    G1
    R1
    --
    B2
    G2
    R2
    Vertex1
    Vertex0
    --
    Vertex2

    Gouraud, Texture
    0x35
    0x01
    0x08
    0x09
    CBA
    V0
    U0
    TSB
    V1
    U1
    --
    --
    V2
    U2
    --
    B0
    G0
    R0
    --
    B1
    G1
    G1
    --
    B2
    G2
    G2
    Vertex1
    Vertex0
    --
    Vertex2



    Fig. 5-30 Packet data structures for 4 vertex polygons




    Modeling data (TMD format) (cont.)




    Packet data configuration example -
    For a polygon with 4 vertices and light source calculation
    Bit configuration of mode value
    The primitive section mode value bit configuration is as follows: For the value of each bit please
    refer to "3 vertex polygon with light source calculation."
    Mode value bit configuration
    MSB LSB

    I


    T
    A
    T

    001
    I
    1

    M
    B
    G


    P

    E

    E
    E

    Note: Bit 3 is set to 1 to designate a 4 vertex primitive.
    Fig. 5-31 Mode byte
    Packet data configuration
    Packet data configuration is as follows:


    Flat, No Texture
    0x28
    0x00
    0x04
    0x05
    Note
    B
    G
    R
    Vertex0
    Normal0
    Vertex2
    Vertex1
    --
    Vertex3

    Flat, Texture
    0x2c
    0x00
    0x07
    0x09
    CBA
    V0
    U0
    TSB
    V1
    U1
    --
    --
    V2
    U2
    --
    --
    V3
    U3
    Vertex0
    Normal0
    Vertex2
    Vertex1
    --
    Vertex3

    Note: Has same value as mode.


    Gouraud, No Texture
    0x38
    0x00
    0x05
    0x08
    Note
    B
    G
    R
    Vertex0
    Normal0
    Vertex1
    Normal1
    Vertex1
    Normal2
    Vertex2
    Normal3

    Gouraud, Texture
    0x3c
    0x00
    0x08
    0x0c
    CBA
    V0
    U0
    TSB
    V1
    U1
    --
    --
    V2
    U2
    --
    --
    V3
    U3
    Vertex0
    Normal0
    Vertex1
    Normal1
    Vertex2
    Normal2
    Vertex3
    Normal3



    Fig. 5-32 Mode





    Packet data configuration example -
    For a polygon with 4 vertices and no light source calculation
    Bit configuration of mode value
    The primitive section mode value bit configuration is as follows: For the value of each bit please
    refer to "3 angle polygon with light source calculation."
    Mode value bit configuration
    MSB LSB

    I


    T
    A
    T

    001
    I
    1

    M
    B
    G


    P

    E

    E
    E

    Note: Bit 3 is set to 1 to designate a 4 vertex primitive.
    Fig. 5-33 Mode byte
    Packet data configuration
    Packet data configuration is as follows:


    Flat, No Texture
    0x29
    0x01
    0x03
    0x05
    Note
    B
    G
    R
    Vertex1
    Vertex0
    Vertex3
    Vertex2

    Flat, Texture
    0x2d
    0x01
    0x07
    0x09
    CBA
    V0
    U0
    TSB
    V1
    U1
    --
    --
    V2
    U2
    --
    --
    V3
    U3
    --
    B
    G
    R
    Vertex1
    Vertex0
    Vertex3
    Vertex2

    Note: Has the same value as mode.


    Gouraud, No Texture
    0x39
    0x01
    0x06
    0x08
    Note
    B0
    G0
    R0
    --
    B1
    G1
    R1
    --
    B2
    G2
    R2
    --
    B3
    G3
    R3
    Vertex1
    Vertex0
    Vertex3
    Vertex2

    Gouraud, Texture
    0x3d
    0x01
    0x0a
    0x0c
    CBA
    V0
    U0
    TSB
    V1
    U1
    --
    --
    V2
    U2
    --
    --
    V3
    U3
    --
    B0
    G0
    R0
    --
    B1
    G1
    R1
    --
    B2
    G2
    R2
    --
    B3
    G3
    R3
    Vertex1
    Vertex0
    Vertex3
    Vertex2




    Fig. 5-34 Packet Data





    Modeling data (TMD format) (cont.)




    Packet data configuration example - For a straight line
    Bit configuration of mode value
    The primitive section mode value bit configuration is as follows:
    IIP: With or without gradation
    0: Gradation off (Monochrome)
    Mode value bit configuration
    MSB LSB

    I


    A

    010
    I
    0
    0
    B
    0

    P


    E


    1: Gradation on
    ABE: Translucency processing on/off
    0: off 1: on
    Fig. 5-35 mode
    Packet data configuration
    Packet data configuration is as follows:


    Gradation off
    0x40
    0x01
    0x02
    0x03
    Note
    B
    G
    R
    Vertex1
    Vertex0

    Note: Has the same value as mode.


    Gradation on
    0x50
    0x01
    0x04
    0x04
    Note
    B0
    G0
    R0
    --
    B1
    G1
    R1
    --
    B2
    G2
    R2
    Vertex1
    Vertex0



    Fig. 5-36 packet data





    Packet data configuration example - For a 3 dimensional sprite
    A 3 dimensional sprite is a sprite with 3-D coordinates and the drawing content is the same as a normal
    sprite.
    Bit configuration of mode value
    The primitive section mode value bit configuration is as follows:
    Mode value bit configuration
    MSB LSB
    0 1 1
    SIZ
    1
    A
    B
    0



    E


    SIZ: Sprite size
    00: Free size (Specified by W, H)
    01: 1 x 1
    10: 8 x 8
    11: 16 x 16
    ABE: Translucency processing
    0: off
    1: on
    Fig. 5-37 Mode
    Packet data configuration
    Packet data configuration is as follows:


    Free size
    0x64
    0x01
    0x03
    0x05
    TSB
    Vertex0
    CBA
    V0
    U0
    H
    W

    8 x 8
    0x74
    0x01
    0x02
    0x04
    TSB
    Vertex0
    CBA
    V0
    U0


    1 x 1
    0x6c
    0x01
    0x02
    0x04
    TSB
    Vertex0
    CBA
    V0
    U0

    16 x 16
    0x7c
    0x01
    0x02
    0x04
    TSB
    Vertex0
    CBA
    V0
    U0



    Fig. 5-38 Packet data for sprites




    The TIM format is the screen image standard handled by the PS-X system. TIM data may be directly
    transferred to the PS-X system frame buffer. It may also represent sprite pattern and 3 dimensional
    texture mapping materials.
    Image data modes (color numbers)
    There are four image data modes that can be handled by the PS-X system.
    (a) 4 bit CLUT (color look-up table) (16 colors)
    (b) 8 bit CLUT (256 colors)
    (c) 16 bit Direct color (32768 colors)
    (d) 24 bit Direct color (Full color)
    Since the VRAM of the PS-X system has a 16 bit configuration, only 16 bit or 24 bit data can be directly
    transferred to the frame buffer. However, sprite patterns and polygon texture mapping patterns can be 4
    bit, 8 bit or 16 bit.
    File format
    TIM files have a file header (ID) at the top and consist of several different blocks.
    31(MSB) 0(LSB)
    ID FLAG
    CLUT
    Pixel data
    Fig. 5-39 TIM file format
    All data is in 32 bit binary data strings. And because it is Little Endian (like the 80 x 86), the byte order of
    multiple byte data is such that the low order byte comes first as in Figure 5-40.





    58 Fig. 5-40 Little Endian byte order within files


    ID section
    Expresses file ID. File ID is one word of data and the bit configuration is as follows.
    bit 0 - 7: ID Value is 0x10
    bit 8 - 15: Version number. Value is 0x00
    bit 31 16 15 8 7 0 (LSB)



    Fig. 5-41 File ID word
    Flag section
    Flags are 32 bit data containing information concerning the file structure. The bit configuration is as in
    Figure 5-42.
    When a single TIM data file contains numerous sprites and texture data, the value of PMODE is 4
    (mixed), since data of multiple types is intermingled.
    bit 0 - 2 (PMODE) Pixel mode (Bit length) 0:
    4 bit CLUT
    1: 8 bit CLUT
    2: 15 bit Direct
    3: 24 bit Direct
    4: Mixed
    bit 3 (CF) Whether there is a CLUT or not
    0: No CLUT section
    1: Has CLUT section
    Other: reserved
    Fig. 5-42 Flag word
    CLUT section
    The CF flag of the flag word specifies whether the TIM file has a CLUT section or not. A CLUT is a color
    palette used by 4 bit, and 8 bit mode image data.
    As shown in Figure 5-42, the CLUT section is configured so that the number of CLUT section bytes is at the
    start of the structure followed by the VRAM location information, image size and data body.




    Screen image data (TIM format) (cont.)




    bit 31 (MSB) bit 0(LSB)





    Bnum
    DX
    DY
    H
    W
    CLUT 1 - n


    CLUT
    Section
    data length.
    Unit is
    bytes.
    (Includes
    bnum's four
    bytes). The
    x
    coordinate
    in VRAM.
    The y
    coordinate
    in VRAM.
    Vertical
    direction
    data size.
    Horizontal
    direction
    data size.
    CLUT entry
    (16 bit/
    entry).


    Fig. 5-43 CLUT structure
    In 4 bit mode, 16 CLUT entries make up one CLUT. In 8 bit mode, 256 CLUT entries make up 1 CLUT.
    In the PS-X system, because CLUT is placed in VRAM, the CLUT section of the TIM file is handled as a
    rectangular VRAM image. In other words, one CLUT entry equals one pixel in VRAM. Because of this,
    one CLUT is handled as a rectangular image and in 4 bit mode the height is 1, width is 16 and in 8 bit
    mode the height is 1, and the width is 256.
    It is possible for more than one CLUT to be held in a TIM file. In this case, the multiple CLUT data is
    stored as one image. The configuration of a CLUT entry is as follows.
    bit 15 14
    S
    T P

    10 9

    54

    0(LSB)










    STP
    R
    G
    B
    Semi-transparent control bit
    Red component (5 bits)
    Green component (5 bits)
    Blue component (5 bits)


    Fig. 5-44 A CLUT entry


    5.4



    The Transparent control bit (STP) is valid when used as sprite data and texture data. This is what
    controls whether the sprites and pixels that pertain to polygons are transparent or not. When the STP
    value is 1, pixels of that color will be translucent. Otherwise they will be a non-transparent color. The
    R,G and B bits control the color component.
    If the R, G and B bits are 0 and the STP bit is 0 the pixel will always be transparent. If the R, G and B
    bits are 0 and the STP bit is 1 the pixel will always be non-transparent. These relationships are shown in
    the chart below.
    STP/R,G,B
    Translucent Processing ON
    Translucent Processing OFF
    0,0,0,0
    Transparent
    Transparent
    0,X,X,X
    Not transparent
    Not transparent
    1 ,X,X,X
    Translucent
    Not transparent
    1,0,0,0
    Non-transparent black
    Non-transparent black

    Figure 5-45 STP bit function in combination with R, G, B data
    Pixel data section
    The pixel data section is the image data body. Since the VRAM of the PS-X system has a 16 bit
    configuration, the image data is separated in 16 bit units. The pixel data section is configured as
    follows:
    bit 31(MSB) bit 0(LSB)


    bnum
    DX
    DY
    H
    W
    DATA 1
    DATA 0
    :
    :

    DATA n
    DATA n-1



    Pixel data section data length. Unit is bytes. Includes the 4 bytes of bnum.
    The x coordinate in VRAM
    The y coordinate in VRAM Vertical direction data size
    Horizontal direction data size (16 bit units)
    VRAM data (16 bit)


    Fig. 5-46 Pixel data
    The configuration of 1 piece of VRAM data (16 bits) varies with the image data mode. The configuration of
    each mode is as shown in diagram 9.

    Be careful when handling the pixel data size in TIM data. Because the width value (horizontal width) in
    Fig. 5-46 is in 16 bit pixel units, the actual image size in 4 and 8 bit mode will be 1/4 and 1/2,


    61




    Screen image data (TIM format) (cont.)




    respectively. Thus the image size horizontal width in 4 bit mode must be a multiple of 4 and in 8 bit
    mode must be an even number.
    (a) In 4 bit mode
    bit 15 12 11 87 43 0(LSB)
    pix 0-3 pixel value (CLUT Index)
    The order on the screen is from the left, i.e. 0, 1, 2, 3.
    (b) In 8 bit mode
    bit 15 87 0(LSB)






    pix 0-1 pixel (CLUT Index)
    The order on the screen is from the left, i.e. 0, 1.
    (c) When 16 bit mode
    bit 15 14
    S
    T P

    10 9

    5 4

    0(LSB)










    STP
    R
    G
    B
    Transparent control bit (See CLUT section)
    Red component (5 bits)
    Green component (5 bits)
    Blue component (5 bits)


    Fig. 5-47 VRAM data (pixel data)



    BGD format is the standard for data configuring BG (background) surfaces using 2 dimensional
    systems.
    BGD files normally use the same name as the TIM file (the file base name is the same) and the actual
    pixel images are held by the TIM file.
    File format
    A BGD file has a header file at the top and is divided into three blocks. However it is possible to omit the
    ATTR section.
    HEADER
    MAP
    ATTR
    Fig. 5-48 BG File format
    Header section
    This is the file header. It is configured as follows.
    31 (MSB) 0(LSB)
    FLAG
    VERSION
    ID
    CELLH
    CELLW
    MAPH
    MAPW

    ID
    VERSION
    FLAG
    MAPH
    MAPW
    CELLH
    CELLW
    0x23
    0x00
    See Fig. 5-49
    BG Map data vertical direction size (Unit is cell) BG
    Map data horizontal direction size (Unit is cell) Cell
    data vertical direction size (Unit is cell) Cell data
    horizontal direction size (Unit is cell)


    Fig. 5-49 BG Header format



    5.5


    BG map data (BGD format) (cont.)




    The FLAG in Figure 5-48 has the following bit configuration
    31 16
    A
    T
    T
    A
    T L



    Reserved




    ATT Whether or not the ATTR block is included in this file 0:
    ATTR is not included
    1: ATTR is included
    ATL ATTR data length
    0: 8 bits
    1: 16 bits
    Figure 5-50 Flag half word structure
    MAP Section
    A map is considered as a set of the cells of MAPH x MAPW (a matrix of the vertical and horizontal size)
    which describes the order of arrangement of these cells. For example the arrangement of the cells of an 8 x
    8 map would be as follows.




    0
    1
    2
    3
    4
    5
    6
    7



    8
    9
    10
    11
    12
    13
    14
    15



    1
    6
    1
    7
    1
    8
    1
    9
    2
    0
    2
    1



    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63

    Fig. 5-51 Cell arrangement in MAP (when 8 x8)
    The Map section is an aggregate of cell numbers arranged in numerical order in a form like that in
    Figure 5-50 (See Figure 5-51). Cell number is a number which indicates the number of the cell in the
    CEL file.
    31(MSB) 0(LSB)
    CELL No.(1) CELL No.(2)



    : :

    Fig. 5-52 MAP


    5.5



    ATTR section
    Indicates attribute data. Attribute data is additional information concerning the MAP and is arranged in the
    same order as MAP.
    There are two types of attribute data, 8 bit data and 16 bit data and each is as follows. Data length is
    indicated in the Header section, in the ATL bit in the FLAG.
    31(MSB) 0(LSB)


    ATTR3 ATTR2 ATTR1 ATTR0
    : :
    Fig. 5-53 ATTR (8 bit)
    31(MSB) 0 (LSB)
    ATTR1 ATTR0
    ATTR3 ATTR2
    : :



    Fig. 5-54 ATTR (16 bit)



    CEL format describes the pointer table in VRAM of CELL, a component of BG surfaces.
    File format
    There is a header file at the top of a CEL file and a CEL file is divided into 3 blocks.
    HEADER CELL
    ATTR
    Fig. 5-55 Cell File Format
    Header Section
    This is the file header. It has the following configuration.
    31(MSB) 0(LSB)
    FLAG
    VERSION
    ID
    RESERVED
    NCELL

    FLAG See Figure 5-57
    ID 0x22
    VERSION 0x00
    NCELL Cell data number (unit is cell)
    Fig. 5-56 CEL file header
    The FLAG in Figure 5-56 has the following bit configuration.
    31 16

    Reserved


    ATT:
    ATL
    Whether or not the ATTR block is included in this file
    0: ATTR is not included
    1: ATTR is included
    ATTR data length
    0: 8 bit
    1: 16 bit
    66

    Figure 5-57 CEL file flag half word format


    5.6



    CELL section
    This is a table of pointers to cells in VRAM, which is a component of BG. 4 bytes corresponds to
    one cell.
    31 (MSB) 0 (LSB)


    CBA
    v
    u
    TSB

    FLA
    G
    CBA
    v
    u
    TSB

    FLA
    G
    :
    :




    See Figure 5-59
    The vertical offset from the texture page base address (8 bits)
    The horizontal offset from the texture page base address (8 bits)
    See Figure 5-60
    See Figure 5-61
    Figure 5-58 CEL section format
    The CBA in Figure 5-58 has the following bit configuration.
    31 16
    C C
    L L
    Y X

    CLY CLUT lead Y coordinate (9 bits)
    CLX CLUT lead X coordinate (6 bits)
    Fig. 5-59 CBA half word format


    5.6


    Cell data (CEL format) (cont.)




    The TSB in Figure 5-58 has the following bit configuration.
    31 16
    Reserved
    T
    P
    A
    B
    TPAGE


    R


    TP
    Pixel depth of texture pattern

    00:
    4 bit CLUT

    01:
    8 bit CLUT

    10:
    16 bit
    ABR
    Translucence rate (F = foreground, B = background)
    00: 0.50xF +0.50xB
    01: 1.00F + 1.00xB
    10: 0.50F + 1 .00B
    11: 0.25xF + 1 .00B
    TPAGE Texture Page number
    01000: (512,0) 11000:
    (512, 256) 01100: (768,
    0) 11100: (768, 256)
    Figure 5-60 TSB format
    The FLAG in Figure 5-58 has the following bit configuration.
    15 0

    H V L L
    P P

    TP Texture pattern pixel depth
    HLP Horizontal inversion information
    VLP Vertical inversion information
    Figure 5-61 FLAG format for CEL entries
    ATTR section

    Expresses attribute data. Attribute data is additional information concerning the cell and is arranged in
    the same order as CEL.

    There are two types of attribute data, 8 bit length data and 16 bit length data and each would be as
    follows. Data length is indicated in the Header section, in the ATL bit in the FLAG half word.



    5.6
    31 (MSB) 0(LSB)




    ATTR3 ATTR2 ATTR1 ATTR0
    : :
    Figure 5-62 ATTR format (8 bit)
    31 (MSB) 0 (LSB)
    ATTR1 ATTR0
    ATTR3 ATTR2
    : :
    Fig. 5-63 ATTR format (16 bit)


    ANM format prescribes information for animating pictorial image data. The ANM file is normally used in
    tandem with the TIM file and the actual pixel images are held by the TIM file.
    File format
    ANM files have a header at the beginning and are divided into 4 parts.
    HEADER
    SEQUENCE
    SPRITEGp
    CLUTGp
    Fig. 5-64 ANM File Format
    HEADER section
    This is the file header. It has the following configuration.
    31(MSB) 0(LSB)
    FLAG
    VERSION
    ID
    NSEQUENCE
    NSPRITEGp



    ID
    VERSION
    FLAG
    NSEQUENCE
    NSPRITEGp


    0x21 0x00
    See Figure 5-
    66 Sequence
    data number
    Number of
    Sprite groups


    Fig. 5-65 ANM header format
    The FLAG in Figure 6-65 has the following bit configuration.
    31 16

    Reserved

    CLUT number for color animation

    Fig. 5-66 FLAG half word format


    5.7



    SEQUENCE section
    This is sequence data. Sequence data is a list of coordinates, display times and sprite group numbers for
    hot spots for each frame.
    31 (MSB) 0 (LSB)


    TI ME SprGpNo
    Y X
    TIME SprGpNo
    Y X

    TIME Display time (number of repeats)
    SprGpNo The sprite group number
    X X coordinate of hot spot
    Y Y coordinate of hot spot
    Fig. 5-67 Sequence
    SPRITEGp section
    This is a Sprite group set. A sprite group describes a location that a given sprite will be displayed at in
    one frame.
    The configuration of a sprite group section will vary with the size of the sprite as in Figures 5-68 and
    5-69.
    31(MSB) 0(LSB)
    NSprite

    Ofs Y
    Ofs X
    v


    u
    FLAG

    CBA

    Ofs Y
    Ofs X
    v


    u
    FLAG

    CBA





    NSprite
    Ofs Y Of s X v u
    FLAG CBA




    Information data (ANM format) (cont.)




    31(MSB) 0(LSB)
    NSprite

    Ofs Y
    Ofs X
    v
    u
    FLAG
    CBA
    H
    W
    Ofs Y
    Ofs X
    v
    u
    FLAG
    CBA
    H
    W

    NSprite

    Ofs Y
    Ofs X
    v
    u
    FLAG
    CBA
    H
    W



    Fig. 5-69 SPRITEGp (variable sprite size)


    The number of sprites within in one sprite group
    See Figure 5-70
    The vertical offset from the texture page base address The
    horizontal offset from the texture page base address The
    vertical offset from the hot spot in the frame The horizontal
    offset from the hot spot in the frame Described earlier
    The texture width of the desired size
    The texture height of the desired size


    5.7



    The FLAG in Figures 5-68 and 5-69 have the following bit configuration.
    31 16


    T

    R
    R

    T
    A

    H

    OS

    P
    B
    TPAGE
    W

    T
    Z


    R


    THW The rectangular area size of the sprite divided by 8 (When cannot be divided by
    8, leave as 0x0 and specify the actual size in H and W above).
    ROT Whether rotates or not.
    0: Does not rotate.
    1: Does rotate.
    RSZ Whether expands and contracts or not.
    0: Does not expand and contract.
    1: Does expand and contract.
    TP Pixel depth of texture pattern.
    00: 4 bit CLUT.
    01: 8 bit CLUT.
    10: 16 bit.
    ABR Translucence rate.
    00: 0.50xF + 0.50xB.
    01: 1 .00xF + 1 .00xB.
    10: 0.50xF + 1 .00xB.
    11: 0.25xF + 1 .00xB.
    TPAGE Texture Page number (0-31)
    Figure 5-70 FLAG half word format
    When rotation, or expansion/contraction has been specified, the following data will be appended after the
    sprite definition.
    31 (MSB) 0(LSB)
    Reserved ROT
    Y X


    ROT Rotation angle
    Y, X Expansion/contraction rate (fixed point designation)
    Fig. 5-71 Rotation, expansion/contraction designation




    Information data (ANM format) (cont.)




    CLUTGp section
    A set of CLUT groups used when doing color animation. The CLUT number is specified by the CLT of the
    flag structure of the header section.
    31 (MSB) 0(LSB)

    bnum
    DY
    DX
    H
    W
    CLUT 1
    CLUT 0


    CLUT num
    CLUT 0
    bnum
    DY
    DX
    H
    W
    CLUT 1
    CLUT 0

    CLUT num
    CLUT num-1



    CLUT data length (bytes)
    The x coordinate in VRAM
    The y coordinate in VRAM
    The horizontal data size The
    vertical data size CLUT entry
    (16 bit/entry)
    Figure 5-72 CLUTGp structure


    appendix





    Controller Pad (DTL-H500C) Button Layout
    Designing operating mode
    D. Controler (DTL-H50C) Buton arangement/bit corespondence diagram A1.
    Controller (DTL-H500C) button arrangement/bit correspondence diagram N L

    Bit no. Corresponding
    button


    Value of each bit 0:
    Not Pressed 1:
    Pressed
    Note: This diagram indicates the button
    configuration arrangement of the
    controller used in the target box for
    development. Please see the following
    page for the controller for the actual PS-
    X machine (the product with the final
    specifications.


    appendix





    Controller Pad (Final Specification) Button Layout
    Controller (product with final specificatons) Button arrangement/bit correspondence diagram
    B1. Controller (product with final specifications) button arrangement/bit correspondence diagram
    L N



    Bit no.
    Corresponding
    button

    15
    C
    Value of each bit
    14
    B
    0: Not Pressed
    13
    D
    1: Pressed
    12
    A

    11
    H

    10


    9


    8
    K

    7
    G

    6
    F

    5
    P

    4
    E

    3
    L

    2
    N

    1
    M

    0
    O
     
  2. Barc0de

    Barc0de Mythical Member from Time Immemorial

    Joined:
    Oct 29, 2005
    Messages:
    11,205
    Likes Received:
    23
    wow, thanks ^_^
     
  3. Alchy

    Alchy Illustrious Member

    Joined:
    Apr 6, 2004
    Messages:
    6,216
    Likes Received:
    21
    Excellent stuff, very generous.
     
  4. Piratero

    Piratero Peppy Member

    Joined:
    Feb 28, 2009
    Messages:
    367
    Likes Received:
    8
    Excellent document! Thank you! Is this freely available on the net or do you own a hard copy of the manual?
     
  5. H360

    H360 Familiar Face

    Joined:
    Mar 5, 2011
    Messages:
    1,474
    Likes Received:
    1
    Got a .PDF or .TXT file of it? PM me so I know...
     
  6. Gemini

    Gemini Retro developer

    Joined:
    Apr 1, 2008
    Messages:
    406
    Likes Received:
    88
    It's a little too late now, but make you sure you've checked your Private Message folder.
     
    Last edited: May 2, 2011
  7. vexatious

    vexatious Rising Member

    Joined:
    Nov 9, 2014
    Messages:
    71
    Likes Received:
    7
    Interesting. It appears this PSX-OS (API or OS?) is oriented towards high level programming and avoiding assembly first hand, if someone wants to code around it. I'm assuming it still allows low level assembly considering they give out the R3000A registers. Is this some kind of OS like DOS for the PSX? I know Windows 95 allows low level hardware access via VXD drivers and protected mode memory via assembly, but it also makes things easy with C and kernel functions (DOS lets you use BIOS functions via assembly).
     
  8. smf

    smf mamedev

    Joined:
    Apr 14, 2005
    Messages:
    1,259
    Likes Received:
    92
    PSX-OS is very much like MSDOS, but Sony forbid you to hit the hardware like you did on the PC. You are even supposed to call the OS through their library rather than calling it directly. You had to supply linker map files when you submitted the game, which supposedly they used to check that you weren't doing anything against the rules. Some games did slip past inspection that broke the rules though.

    You can code in assembly on any platform, it's just harder. I think they expected you to do minimal amount of assembly language processing with the majority of the game in C.

    For homebrew then there are no rules, but you have to test on the multitude of PS1 hardware variants. The hardware has functionality that the libraries never exposed, but it's often not the same on the different chipsets.
     
  9. l_oliveira

    l_oliveira Officer at Arms

    Joined:
    Nov 24, 2007
    Messages:
    3,894
    Likes Received:
    252
    That very much sums the whole point of NOT acessing the hardware directly. For example PS1s with PU18 or 20 boards (not sure which one started having it) have a scope feature for it's audio CD player. So the CD drive chipset has some sort of feature which allows for analysing the data that is read from the disc so it can be used to generate the patterns for the screen effects.

    No game is supposed to use that as obviously older models lack that feature.
     
  10. smf

    smf mamedev

    Joined:
    Apr 14, 2005
    Messages:
    1,259
    Likes Received:
    92
    IIRC the scope just dma'd out the data from the spu ram buffer & the scope wasn't in older bios just because they hadn't coded it.
    I seem to recall some unofficial software by datel (or similar) that used the same trick for loading data that was encoded onto audio cd's.
    There was a game that used it too (Vib-Ribbon), you put in an audio cd and it tailored the game to the music.

    Early emulators never bothered with emulating the mixing buffer, I don't know what the state of play is today.

    Using the official libraries doesn't guarantee your game will run on all hardware and all emulators. Although it's more likely to work on real hardware as the timing changes were less extreme and you were supposed to test on all variants. Timing on emulators is a joke, there are no accurate emulators.
     
    Last edited: Nov 20, 2014
  11. l_oliveira

    l_oliveira Officer at Arms

    Joined:
    Nov 24, 2007
    Messages:
    3,894
    Likes Received:
    252
    If you put the newer BIOS with the scope on older motherboards, the scope does not work.
     
  12. smf

    smf mamedev

    Joined:
    Apr 14, 2005
    Messages:
    1,259
    Likes Received:
    92
    Try Vib Ribbon on one of those consoles and see what happens. It might not be missing hardware, it might just be a bug in the BIOS as they wouldn't have tested it on an older console.
     
  13. l_oliveira

    l_oliveira Officer at Arms

    Joined:
    Nov 24, 2007
    Messages:
    3,894
    Likes Received:
    252
    I think you might want to actually *look* inside the newer BIOS. We might be talking of different things. And I knew about Vib Ribbon and how it reacts to the spectrum of the waveforms on the music disc you put in. The original CD-XA chip (which is used on the early PU-7 PlayStation mobos) had information on it's datasheet about that feature.

    The BIOS with scope definitely need the newer CD drive hardware to work properly.
     
  14. smf

    smf mamedev

    Joined:
    Apr 14, 2005
    Messages:
    1,259
    Likes Received:
    92
    I'll take a look, I had assumed both used what doomed wrote about in 1999. I've not really concentrated on sound yet.

    "In the first 4 kb of the buffer the SPU stores the decoded data of CD audio
    after volume processing and the sound data of voice 1 and voice 3 after
    envelope processing. The decoded data is stored as 16 bit signed values,
    one sample per clock (44.1 khz)."

    It should easily be possible to do a scope using that, it seems odd they'd add extra hardware.
     

Share This Page