Quake II Scene Builder (version 1.0 February 01, 1998).

Quake II Scene Builder(QSB)is a program that allows you to view the
models (monsters and other objects) that appear in the
game Quake 2 from id Software.

    Features:
    * Load from .md2 or .pak files.
    * Automatically loads related textures.
    * Animation.
    * User controlled lighting effects.
    * Save to bitmap files.
    * Load more than 1 model at a time.
    * "CAD like" interface for placing objects.
    * Uses OpenGL for high quality rendering.

    Requirements:
    * Windows 95 (OpenGL dll's may have to be downloaded separately)
      or Windows NT.
    * At least a Pentium 166 (may work on lesser processors).
    * Video card capable of 16 bit color at 1024 x 768 or better.
    * Video card that accelerates OpenGL recommended.

Price

    This version of QSB is freeware.

DISCLAIMER

    Users of QSB must accept this disclaimer of warranty: "QSB is
    supplied as is.  Binary Alchemy disclaims all warranties,
    expressed or implied, including, without limitation, the
    warranties of fitness for any purpose.  The author assumes no
    liability for damages, direct or consequential, which may result
    from the use of QSB."

Feedback

    I have been developing this program for the last month or so in a
    vacuum. I will continue to enhance and improve this
    program as long people show interest and I am amused by it.
    Please send any comments, suggestions, bug reports. job
    offers, etc. to pjs@ce.mediaone.net

Contributions

    All of the icons, toolbar bitmaps etc. in this version suck and I
    can't draw.  If anyone would like to contribute art
    let me know (pjs@ce.mediaone.net).

Credits:

    Programming, design, etc.:  Patrick J. Simmons
    (pjs@ce.mediaone.net)

    Thanks to:
        id Software.
        Trey Harrison whose md2view source was a big help.
        All of the people who answered my questions on the OpenGL
        news group.
        Everyone who downloaded the pre-release version, and sent in
        bug reports and
        comments.

The balance of this document is divided into 3 sections:

    Instructions
        A walk through, tutorial approach to using the program.

    Reference
        A brief explanation of the buttons and menu items.

    Trouble Shooting
        Answers to common questions.
-----------------------------------------------------------
Instructions:

    These instructions walk you through the features of the program.

    Take a few minutes following these instructions to familiarize
    yourself with the program.

    Loading a model:
        1. From the main menu select File->Open.

        A file open dialog will appear, select the appropriate file
        type.

        2. For now, open the pak0.pak that comes with Quake2.
        (This file can be found in the baseq2 sub-directory or on the
        Quake2 CD-ROM).

        After opening this file, you will notice that another window
        entitled "Scene Properties" appears.

        3. Click on the tab labeled Pak File.  You will see a list of
        model categories, each with a small plus to the
        right.

        4. Click on the plus next to "monsters".  A list of monsters
        will appear.

        5. Click on the word "soldier" and then click on the view
        button.

        In a few moments, the gunner model should appear, along with
        a new window labeled "Object Properties".

    Animating the model:
        1. In the Object Properties window, click on the tab labeled
        "Skin/Animation"

        2. Click the "Play" button.

        3. Adjust the speed of the animation with the slider.

        The default setting will play through all of the animations
        defined for the model.

        Selecting an animation:
            The drop down list under animation lists all of the
            animations.
            Choose "runs", click the "Loop" check box off and click
            the play button.

            The program will play the "runs" animation sequence once
            and stop.

        Single stepping through animations:
            Set the "Single Step" check box on.
            Now the play button will advance the animation one frame
            per click.

    Changing the Skin:
        1. In the "Object Properties" Window, click on the tab
        labeled "Skin/Animation"

        The drop down list under Skins lists all of the skins that
        were loaded.

        Select "pain" and notice how the soldier's appearance
        changes.

        The check box labeled "Effected by Lighting" determines
        whether or not the lights effect the color of the model,
        experiment now to see the impact.

        (The yellow wire frame ball is a light)

        You can load a .bmp or .pcx file as the skin at any time.

    Moving the Camera:
        The fourth set of buttons in the toolbar allow you to move
        the camera.

        If you move the mouse pointer over a button and wait, a tool
        tip will appear and the buttons function will be
        displayed in a tool tip and in the status bar located at the
        bottom of the screen.

        Pan:
            Pan moves the camera up, down, left, right, in, and out.

            Holding the left mouse button down and moving the mouse
            left and right moves the camera left and right.
            Holding the left mouse button down and moving the mouse
            up and down moves the camera in and out.
            Holding the right mouse button down and moving the mouse
            up and down moves the camera up and down.

            Try it!

            The camera can be reset to a preset value by selecting
            View->Camera from the main menu.
            Perspective is the initial value.

            You can restrict the movement by selecting one or more of
            the buttons in the fifth set of buttons (Effect ...).

        Orbit:
            Orbit moves the camera around an imaginary sphere that is
            centered at the origin of the scene.

            Holding the left mouse button down and moving the mouse
            left and right orbits the camera along the X axis.
            Holding the left mouse button down and moving the mouse
            up and down orbits the camera along the Y axis.
            Holding the right mouse button down and moving the mouse
            up and down orbits the camera along the Z axis.

            Again, movement can be restricted by using the buttons on
            the right.

            Right click in the "Scene Window", a pop-up menu will
            appear, try selecting Grid, and Axis Markers.
            These make it easier to keep your place in 3d space.

            You turn them off the same way that that you turn them
            on.

        Zoom:
            Zoom changes the distance between the camera and the
            center of the scene.

            Hold down the left mouse button and move the mouse left
            and right to see the effect.

        FOV:
            FOV stands for "Field of View".  It is not unlike zoom.

            Hold down the left mouse button and move the mouse left
            and right to see the effect.

            Notice the grid while moving it too get a better feel for
            what it does.

            The default FOV is 45, if you what the lower left corner
            of the screen while changing the FOV, you can set it
            to a specific value.

            (note: a better explanation to follow).

    Moving the Object (model):
        The second set of buttons moves the model within the scene.
        Before we continue, go to the main menu and select
        View->Four Viewports.

        The scene window will now be divided into four sub windows,
        three 2D wireframe views and one fully rendered 3D
        view. Each of the 2D views has a label that describes where
        the camera is.

        The second set of buttons control what the mouse will effect.

        Select:
            The soldier should be selected.  The selected object is
            always drawn in white on the 2D viewport, objects not
            selected will be drawn in blue, lights that are not
            selected are drawn in yellow.

            You select an object by clicking on it.

        Move:
            The second button allows you to move the model.

            In the 2D viewport, the model is moved in the direction
            of the mouse.  Hold the left mouse button down and move
            the mouse in a 2D view.  You will notice that the detail
            of the object is replaced by a bounding box.  You can
            toggle this behavior by selecting View->FastMove from the
            main menu.

            In the 3D view, the model is moved as follows:
                Holding the left mouse button down and moving the
                mouse left and right moves the object left and right.
                Holding the left mouse button down and moving the
                mouse up and down moves the object in and out.
                Holding the right mouse button down and moving the
                mouse up and down moves the object up and down.

            The effect of the mouse can be limited by selecting from
            the left most group of buttons.

        Rotate:
            The third button allows you to rotate the model.

            You can rotate the object around one axis at a time.  You
            choose the axis by selecting one the buttons labeled
            X, Y or Z.  Hold the left mouse button and move the mouse
            left and right.

            Note: The center of the rotation cannot be changed in
            this version of the program.

        Scale:
            The fourth button allows you to scale (change the size)
            of the model.

            The buttons labeled X, Y and Z determine how the scaling
            is applied.
            If you select all three, the effect will be uniform,
            otherwise, the effect will be more like stretching.

            Hold the left mouse button down and move the mouse left
            and right to see the effect.

    The Viewport:
        The Scene window shows either one or four viewports.  If you
        are looking at four viewports now, go back to one by
        selecting View->One Viewport from the main menu.

        The Viewport that you are looking at now is one that you
        performed the last operation in.

        Right clicking in the Viewport invokes a pop up menu that
        allows you to control the appearance of the viewport.

        Here are the menu items:
            Grid                Toggles the visibility of the grid in
            the view.
            *Axis Markers       Toggles the visibility of the axis
            markers in the view.
            *Highlight Selected Toggles the constant bounding box
            that is around the selected object.
            *Display as         Determines how the scene is rendered.
            Camera              Changes the camera to one the preset
            values.
            Viewport type       Changes the viewport from FastEdit
            (2D) to Preview(3D).
            Properties          Toggles the "Object Properties"
            window.

            * available in the Preview viewport only.

        If you are looking at one 2D viewport, right click and select
        Viewport Type->Preview.

    Lighting:
        Some dramatic effects can be achieved by using lighting.
        Note that Quake 2 does not use the lighting features of
        OpenGL as this program does, so the effect of lighting on the
        models is more subtle then dramatic.

        Click on the "Skin/Animation" tab in the Object Properties
        window. (If this Object Properties window says "no
        selection" then click on the Soldier in the Scene window).

        Change the skin to <none>

        The model should now appear as a smooth shaded object (no
        texture or skin).

        Click on the "Material" tab in the Object Properties window.

        Select "brass" from the Preset drop down list.

        The material properties determine how the object reacts to
        the lights in the scene.
        With one exception, the Emission property.

        Click on the Emission button.

        The Color Picker window will appear.

        The Color Picker allows you to set a properties color by
        adjusting the Red, Green and Blue components of the color.

        The easiest way to use this window is to pick a color from
        the color bar (located at the bottom of the window) by
        clicking on it, then use the sliders to adjust the color.
        Note that the color bars above sliders tell you how to
        change the color.  If the Color Picker's tab is "No Color
        Selected", the color picker is not active.

        OK, set the Emission color to a shade of blue. Note that the
        model now takes on a blue glow.

        Lets change the properties of the light...

        Click on the "Selector" tab in the Scene Selector window.

        You will see a tree that shows:
            Scene
                Objects
                Lights

        Click on the plus next to Lights, then click on "Default".

        The Object properties window will now show the properties for
        the Default Light.

        Note that there are buttons for Ambient, Diffuse and
        Specular.

        Here is a brief definition of each:
            Ambient
                Is light whose direction is impossible to determine.
                When it hits a surface, it is scattered in all
                directions.

            Diffuse
                Comes from one direction.  When it hits a surface, it
                is scattered in all directions.

            Specular
                Comes from one direction.  When it hits a surface, it
                bounces off in one direction.
                Think of secularity as shininess.

        Take some time to experiment with these properties.

    The Background.

        Click on the "Colors" table of the Scene Selector window.

        This tab allows you to:
            Change the Background Color of the scene.
            Set the Ambient Light for the entire scene.
            Load a picture as the background for the scene.

        Changing the Background Color or Ambient Light is done by
        setting the Red, Green and Blue levels using the Color
        Picker window.

        To load a picture
            Click the load button
            A file select dialog will appear.
            Select any .bmp or .pcx file.

            The buttons labeled Texture, Zoom, and Stretch determine
            how the picture is rendered.

            If you have a video card that accelerates OpenGL, Texture
            is probably the best choice, otherwise, try Stretch.
            In any case the picture is rendered in the same way.
            Note that if you do not have a video card that
            accelerates OpenGL, texture may not work.

    Shadows

        To cast shadows of the model, you must have a light and
        either a plane or floor.

        Since we already have a light, lets add a plane.

        From the main menu select Scene->Objects->Add.

        Select Plane from the list and click OK.

        Position the Plane behind the model (this may be easier using
        the Four Viewport view.. View->Four Viewports from
        the main menu).

        Once you have moved the plane, scale it that it consumes the
        entire display.

        Click on the "Shadows" tab in the Scene Selector window.

        Highlight the Default light and the Plane, then check
        Shadows.

        Try moving the light to see the effect.
            To move the light:
                Select the light:
                    Click the select button on the toolbar (the one
                    that looks like an arrow).
                    Click on the light in the Scene window (the light
                    is the yellow wireframe ball).
                    OR
                    Click on the "Selector" tab in the Scene
                    Properties window and click on "Default" under
                    Lights.

                Click the Move button in the toolbar.

                Move the mouse in the Scene window while holding down
                one of the buttons.
-----------------------------------------------------------
Reference:

    The Main Menu

        File
            New
                Clears the scene, removes all lights, objects and
                models.
                Can also be invoked by clicking the "Clear" button in
                the toolbar.

            Open
                Opens a .md2 or .pak file.

            Save
            Save As
                These will be using in a later version.

            Save Image
                Save what's currently in the Scene window to a bitmap
                (.bmp) file.

            Print
                Prints what's currently in the Scene window.

            Print Preview
                Prints what's currently in the Scene window to a
                Print Preview Screen.

            Print Setup
                Allows you to choose/setup the printer.

            Exit
                Exits the program.

        View

            Toolbar
            Status bar
            Properties
            Scene Properties
            Color Picker
                These toggle the named window on and off.

            One Viewport
                Show one viewport in the Scene window.

            Four Viewports
                Show four viewports in the Scene window.

            Move Fast
                Show the selected object as wireframe box, hide the
                background image, etc.
                Useful if the scene is complicated, and the program
                responds slowly.

            Options
                This brings up the options dialog which, for now
                contains options that will help me to diagnose
                problems you may be having with QSB.

                Both of the check boxes should be clear for normal
                operation.

        Camera
            Perspective
            Front
            Top
            Right
            Left
                Move the camera to a preset position.

        Scene
            Clear
                Same as File->New.
            Lights
                Add a Light or Spot Light.
            Objects
                Add a Plane or Floor.

        Help
            About

    The Viewport Pop-up Menu

        Preview (3D View)
            Grid
                Toggle grid lines.

            Axis Marker
                Toggle the Axis Marker.

            Highlight Selected
                Constantly draws a wireframe box around the selected
                object.

            Display as..
                Points Fast
                Points
                Wireframe
                Wireframe Fast
                Flat
                Shaded (textured)

                    Determine how all of the objects in the scene are
                    rendered.

            Camera
                < see main menu >

            Viewport Type
                Switch between Fast (2D) and Preview (3D) modes

            Properties
                Toggles the Object Properties window on and off.

        Fast Edit (2D View)
            Grid
                Toggle grid lines.
            Camera
                < see main menu >

            Viewport Type
                Switch between Fast (2D) and Preview (3D) modes

            Properties
                Toggles the Object Properties window on and off.

        If you have four viewport showing in the Scene window, you
        can toggle the visibility of any of the viewports from
        this menu.

    The Scene Selector Window

        Selector
            This tab allows you to select an object (model) or light
            by clicking on it's name.
            You can add an object (plane, floor) or light.
            You can delete the selected object (model) or light.

        Color
            This tab allows you to:
                Set the scene's Background Color.
                Set the Ambient light for the scene.
                Select, hide, or clear the Background image for the
                scene.
                    The Texture, Zoom, Stretch options determine how
                    the background image is drawn.
                    Select the option that provides the best
                    performance for your system. (note that texture
                    may not work
                    on some systems).

        Textures
            This tab allows you to add and delete textures that are
            applied to planes and floors.
            The quality options control the overall quality of all
            the textures and skins in the scene.

        Shadows
            This tab allows you to select a light and a plane or
            floor that will be used to render shadows.
            You toggle shadows on and off.
            You can select the color that the shadow is rendered in.
            See the section "Shadows" in the instructions for more
            information.

        Pak File.
            This tab allows you to select a model from within a
            loaded .pak file.

            The .pak file that comes with Quake 2 is named pak0.pak
            and is normally found in the baseq2 directory.
            Note that if you choose the minimal installation, this
            file will be on the Quake2 CD.

    The Object Properties

        Objects / Models
            General
                This tab allows you to change the name the the
                program will refer to the object as.
                You can also toggle the objects visibility, or delete
                the object from the scene.
                If the object is a Floor or Plane, Complex changes
                the number of triangles used to render the object.
                If
                you are shining a spot light on a floor or plane
                check Complex.

            Material
                This tab allows you to set the color values for all
                of the objects material properties.
                You can also make the object transparent by moving
                the slider to the right.

                Note that Quake 2 does not use the lighting features
                of OpenGL as this program does, so the effect of
                lighting on the models is more subtle then dramatic.

            Skin/Animation (Models only)
                Skin
                    Allows you to select from any skin loaded for
                    this model.

                    Load allows you to load any .bmp or .pcx file and
                    apply it as a skin.
                    Note that applying a skin that was not designed
                    specifically for the model will give less that
                    desirable results.

                    Effected by Lighting toggles the effect of any
                    lights in the scene.

                Animation
                    If animations were defined for the model, they
                    will be listed in the drop down list.

                    If you select all, all animations will play in
                    the order that they were defined.

                    The Play button starts the animation, the Stop
                    button stops it.

                    You control the over all speed of the animation
                    with the speed slider.

                    You can single step through the frames of
                    animation by checking Single Step and clicking
                    the play
                    button to advance the frame.

                    If Loop is check the animation will repeat over
                    and over again.

            Texture (Text, Planes and Floors only)
                This tab allows you to load and assign textures to
                Planes and Floors.

                The texture can be any .bmp or .pcx file.

                Effected by Lighting toggles the effect of any lights
                in the scene.

                Reset Matrix resets the effect of changing the
                texture matrix through the toolbar.

            Text
                This tab allows you to enter text that will be
                displayed as a 3D object.

                You can use any TrueType font.

                Extrude is like depth, normal settings are between .1
                and 1.0

        Lights
            General
                This tab allows you to:
                    Change the name the the program will refer to the
                    light as.
                    Set the Ambient, Diffuse, and Specular colors.

                Enable
                    If checked, the light is effecting the scene.

                Visible
                    If checked, the light is display in the scene as
                    a yellow wireframe sphere or cone (spot light).

                Directional/Positional determine how the light
                effects the scene.

                Delete removes the light from the scene.

            Spot (Spotlights only)

                If you add a Spot Light, this tab will be available.
                Use the two sliders to adjust the size and focus the
                light.

                Note that Spot Lights work best when they are shinned
                on Floors and Planes with Complex checked.

    The Color Picker

        This window allows you to change the red, green and blue
        components of the selected color.

        The larger rectangle on the bottom can be used to select a
        color by clicking on the color you desire.

        The individual sliders allow you to adjust to color
        components individually.  The effect of moving a slider is
        predicted by the color bar above each slider.

        Note that the name of the object and property is displayed on
        the tab in the Color Picker window, if the name is
        "No Color Selected", the Color Picker has no effect.

    The Toolbar
        The buttons from left to right are:

            Clear
                see Menu->File->New
            Open
                see Menu->File->Open
            Save
                not currently available.

            Select
                The mouse selects an object when the pointer is over
                the object and the left button is pressed.

            The following control what the mouse does if it is moved
            with a button pressed in the Scene Window.

                Move
                    The selected object is moved in the scene. See
                    "Moving the Object, Move" in the instructions.

                Rotate
                    The selected object is moved in the scene. See
                    "Moving the Object, Rotate" in the instructions.

                Scale
                    Changes the size of the selected object. See
                    "Moving the Object, Scale" in the instructions.

                Move Texture
                    Moves the texture in the selected textured object
                    (Plane or Floor).

                Rotate Texture
                    Rotates the texture in the selected textured
                    object (Plane or Floor).

                Scale Texture
                    Scales the texture in the selected textured
                    object (Plane or Floor).

                Pan
                    Moves the camera up/down, left/right, or in/out.
                    See "Moving the Camera, Pan" in the instructions.

                Orbit
                    Moves the camera around the center of the scene.
                    See "Moving the Camera, Orbit" in the
                    instructions.

                Zoom
                    Changes the distance between the camera and the
                    center of the scene. See "Moving the Camera,
                    Orbit" in
                    the instructions.

                FOV
                    Changes the camera's Field of View.

                Mouse Effects:
                    These limit the effect of the mouse to one or
                    more axis or direction.
                    In is on.
                        X (left/right)
                        Y (up/down)
                        Z (in/out)
    The Status Bar
        Explains the purpose of the toolbar buttons.
        Shows the effect of move and scale operations.

    Player
        The models and skins for the player that are used in
        multi-player games are not stored in the .pak file.  They are
        in separate directories under the qbase2 directory.  When you
        load a player model, the program will not
        automatically load the skins (a message box will pop up), you
        must load them manually using the Load Skin button in
        the "Skin/Animation" tab of the Object Properties window.

Trouble Shooting
    If you discover a bug in QSB, please send a description of the
    bug and a detailed explanation of what you did to cause
    the bug to appear to pjs@ce.mediaone.net.

    Here are answers to some common questions:

    Q) How come this program runs so slow?
    A) This program was designed to run on computers with Pentium II
    processors and 3D accelerated video cards.
       If enough people complain, I will attempt to optimize if for
       slower computers.  Try setting Display as Wireframe
       Fast in the Viewport pop-up menu while you set up the scene.
       Certain options (lights, shadows, transparency,
       background images) have a negative impact on performance.
       Turn these options on after the scene has been setup.

    Q) I can't see the model I just loaded, why?
    A) Either add a light or turn off "Effected by Lighting" on the
    "Skins/Animation" page in the Object Properties window.

    Q) Clicking on the Color Picker doesn't change anything, why?
    A) You must select a color in order for the color picker to work.
    If the tab contains the text "No Color Selected",
    the Color Picker won't work.

    Q) When I start the program, I see a message that says glu32.dll
    cannot be found.
    A) You need the OpenGL dll's.  You can download them from the QSB
    Web Site www.planetquake.com/qsb.

    Q) When I start the program, I see a message that says "Missing
    export OPENGL32.DLL:glGenTextures"
    A) You have an older version of the OpenGL dll's. You can
    download the latest version from the QSB Web Site
    www.planetquake.com/qsb.

