Odyssey UI

From StarOdysseyWiki

Jump to: navigation, search
A screenshot of the Odyssey UI
A screenshot of the Odyssey UI

Contents

[edit] A User Interface Control Library for Managed DirectX projects

Every game needs a User Interface and mine is no exception. So here's my attempt to design and develop a complete library of control widgets easy enough to use in every DirectX application. In this page you'll find a brief overview of the project, instruction on how to use it, and the download links.

[edit] Overview

The Odyssey UI is a vector based user interface. That means that it doesn't rely on textured elements to display its widgets. The DirectX SDK sample UI is an example of a textured user interface. It uses a texture file where every widget is drawn. The appropriate portion of the image is extracted at runtime and displayed as a texture. A vector based UI, on the other hand, automatically computes the shape of the control to display and presents it to the user. The most notable example of a vector based UI is Windows XP and Vista. Here are the pro and cons of using this kind of approach.

[edit] Pro

  • You do not need to draw anything. If you, like me, are not skilled at drawing, this is the alternative, that should outweight all other disadvantages. A control's appearance is automatically computed by the system. You only need to specify the size, position and colors.
  • If you decide to change a control's appearance, using a vector based UI, you simply need to change the aforementioned parameters. If you used a textured UI, you'd have to redraw it.
  • Theming is as simple as telling the library to use another different XML-theme file.
  • A vector based UI is extremely fast to render. Most textured UI use textured quads to display their textures. A vector based UI is a collection of vertices, without the textures.
  • If you're poor and can't pay a skilled artist, you have no alternatives.

[edit] Cons

  • Some people could not like the final appearance of the UI. For example, blue translucent windows could not really be that suited to a fantasy role playing game. And although you could change colors and the like, some details are just too complicated to make them easily computed by numerical procedures.
  • A skilled artist should always produce a more beautiful result.

Although the library clearly allows you to display textures and images, it is heavily oriented toward a vector based approach. Theoretically you could extend the PictureBox control and develop a whole new set of controls (or maybe even combine renderable controls with textured ones!).

[edit] Usage

[edit] How do I make it work?

The source code is organized as a class library that can be linked to any C# MDX Project (if you don't want to recompile it). Using the Odyssey UI is very simple, you just have to follow these easy steps.

  1. Reference the AvengersUtd.Odyssey.UserInterface namespace.
  2. Call OdysseyUI.SetupHooks(form) where form is your form object.
  3. Assign to OdysseyUI.Device your DirectX device object. Throughout the code there are several device calls, so this avoids you having to pass the device reference every call.
  4. Create a Hud object. The HUD is the on screen overlay of the User Interface.
  5. Assign the Hud object created this way to be the CurrentHud of the UserInterface: OdysseyUI.CurrentHud = hud;. This allows you to specify different HUDs and change Hud with ease.
  6. Call the hud.BeginDesign(); method to tell the UI that you are beginning to create controls
  7. Create the controls as you would do when coding Windows.Forms applications.
  8. Add them to the HUD container: hud.Controls.Add(control);
  9. Assign events if necessary (see the samples).
  10. When you are done with the design of the UI, call hud.EndDesign();
  11. Finally, in your render loop you just have to: hud.Render();

That's it, you're done!

[edit] How does it work?

It uses a VertexBuffer object to store all the controls vertex structure. They are of the TransformedColored variety. There's also a sprite collection used to manage Labels, rendered via the Sprite DirectX class. When a control status or position changes, the VertexBuffer object is updated with the new information. When you want to dynamically add new controls not already present in the buffer, the interface has to be rebuilt, because controls that are not visible are not considered during the initial computation of the UI vertices. But it still is very fast, nonetheless, because even complex UIs are at most a couple of hundred vertices. Furthermore, since UI updates do not happen every frame, so the performance hit suffered when the interface has to be rebuilt is irrelevant if you consider that it happens once in a while.

[edit] What are some of the main features of the UI?

The User Interface correctly renders multiple windows that could overlap each other.
  • Draggable and modal windows.
  • Shape support: you can specify the appearance of the shape between the following ones:
    • Rectangular
    • Circular
    • Trapezoidal
  • Border Style support:
    • Flat
    • Raised
    • Sunken
  • Control status changes:
    • Highlighted
    • Clicked
    • Enabled
    • Selected
    • Visible
    • Focused
  • Events:
    • All mouse events you can think of, including MouseWheel
    • KeyDown, KeyPress, KeyUp keybord events.
    • You can write delegates for all those events and they be executed when the related event is fired.
  • "Shader" support: you can write your own delegate methods that tell the User Interface how to colorize controls. Default "shaders" included:
    • Top to Bottom shading
    • Bottom to Top shading
    • Left to Right shading
    • Right to Left shading
    • No shading
    • ..and you can define your own method!

[edit] Which controls are contained in the library?

These are the following working controls as of Version 0.3.4:

  • Window
  • DialogBox
  • Label
  • Panel
  • GroupBox (a panel with a flat border and a caption label)
  • Button
  • Trackbar (also known as a slider control)
  • TextBox
  • OptionGroup (a set of radiobuttons)
  • Checkbox
  • DropDownList (also known as a ComboBox)
  • TabPanel (a panel with a set of buttons used to change pages)
  • RichTextArea (a panel that accepts BBcode like formatted input, see this sample)

These controls are not yet complete and will be changed/modified in the future:

  • PictureBox (it works but it has to be polished)
  • DataViewer (see this blogpost)

If the control you need is not listed here, you can either contact me about it, complain in the forums or read this comprehensive guide if you want to create one yourself.

[edit] Requests and Submissions

Do you need control x? Contact me And we'll see what we can do. I'm writing new controls as they are needed by the game. If you want to help with the library, please let me know. If you can, post all your questions in the forum so that everyone interested in the library may benefit from these discussions.

[edit] Can I use it freely?

Of course, you can download it for free and modify the source code as you wish. If you do decide to use it in your project plaese contact me telling me about it so that I can link it here, if you'd like.

The Odyssey UI is released under the Creative Commons Attribution NonCommercial license.

[edit] Download

What's new in version 0.3.4.

[edit] See also

Retrieved from "http://www.avengersutd.com/wiki/Odyssey_UI"
Personal tools
related