Archive:Basic overview of the XBMC source code

XBMC's main program code (including the GUI library) is developed in Microsoft Visual Studio .NET. The source code is programed in C++ programming language (and some assembly programming language), and uses Microsoft DirectX multimedia framework, (the Xbox does not support OpenGL). Some of the XBMC libraries are also in C programming language but those then uses a C++ wrapper and/or are loaded via XBMC's own DLL loader (which uses Microsoft Windows dynamic-link library standard). The Xbox embedded Operating-System/BIOS is Win32-based (same as Microsoft Windows operating-system) but it does not have all of the resources or capabilities of a full Microsoft Windows Operating-System, (for example: DirectShow, Windows Registry, nor DLLs are nativly supported on the Xbox, and XBMC have to emulate any kernel32 functions is such calls are made). Because of the constraints on the hardware and environment of the Xbox all software development for XBMC are focused on reserving the limited resourses that exist, the main hindrance of which is the amount of available RAM (random access memory) at any one time. Team-XBMC developers also try to keep the code as modular and dependent free as possible, it makes it easier to debug and keeps the alternatives open for future cross-platform version of XBMC.

Note! If you have any further questions, developers can be found in #xbmc on FreeNode (IRC) from time to time.

Xbox Development Environment

It is important to always keep in mind all the aspects of the Xbox environment when developing XBMC for the Xbox.

Hardware

• Xbox only has a 733Mhz Intel Pentium III CPU running on a 133MHz FSB (supporting MMX/MMX2 and SSE SIMD Extensions)
• The Xbox only has 64MB of shared RAM (memory is shared between CPU and GPU)
• Xbox GPU is a nVidia NV2A running at 233MHz (somewhat in between GeForce 2 and GeForce 3 series)
• The APU (Audio Processing Unit) is a nVidia MPC (designed for Xbox, a.k.a. MPCX), which only support 48Khz-output
  • The APU is integrated to the MPCX APU and can encode to A-channel C3 audio on-the-fly in hardware
• The Xbox-chipset can be described in layman terms as something similar to the first nVidia nForce chipset
  • The chipset designed by nVidia and makes up a southbridge (the MPCX-1) and the GPU (NV2A)
• Most Xbox DVD-ROM drives are made by Philips/Thomson/Hitatchi and can't read CD-R media
  • DVD-ROM drives made by Philips/Thomson/Hitatchi can not read CD/DVD subchannels either
    • Samsung made Xbox DVD-ROM drives can read CD-R media and sub-channels (like CD+G)

Operating-System

• The Xbox does not have a Operating-System per-say, instead it only has a basic BIOS
  • Everything else must go into the XBMC executable and it's (XDK and own-made) libraries
• Only a single process-thread (executable) can run at any one time on the Xbox
• Xbox hard drive file-system (FATX) has many limitations, among them a filename maximum of 42-Character characters
• The Xbox has four USB 1.1 ports but the Xbox SDK (a.k.a. XDK) does not contain a full USB-Stack (data structure).
  • if wanted to add support for USB hardware-devices one would have to make/port a USB stack for yourself

XBMC GUI Library

XBMC uses a coded from scratch GUI library (sometimes refered to as "GUI toolkit" ), it functions as a framework which handles all windows, dialogs and controls. The main entry point for the GUI library is the Window Manager, GUIWindowManager.

Window Opening and Closing procedure

Windows are activated and deactivated via the GUIWindowManager::ActivateWindow() routine, and it's counterparts, PreviousWindow() and ReplaceWindow(). The window history (ie previous windows) is kept in m_windowHistory in the GUIWindowManager.

Window Opening

Windows are activated by sending the GUI_MSG_WINDOW_INIT message.

The base class (GUIWindow in guilib) then does the following:

• AllocResources() is called.
  • The windows xml skin file is loaded if not already, and OnWindowLoaded() is called.
  • Controls are created + allocated (other than image textures)

• OnInitWindow() is called.
  • Control states are restored if applicable, including the last focused control. Windows by default remember the default control.
  • Initial control visibility is set.
  • Window open animation is queued.
• Overlay state (whether or not the Music or Video overlays are shown) is updated.

Thus, the derived classes should:

• Do anything that needs to be done before the xml skin file is loaded in the OnMessage() routine.
• Do anything that must be done once the xml is loaded and before resources are allocated in OnWindowLoaded() – the base class just sets m_bDynamicResourceAllocation to true.
• Do anything that must be initialized before the window is shown in OnInitWindow(), and call the base class once everything is ready so that it can restore the saved control states and queue animations etc. Calling ResetControlStates() before calling the base class implementation will open the window in a clean state.

Window Closing

Windows are closed when the GUI_MSG_WINDOW_DEINIT message is sent.

The base class (GUIWindow in guilib) then does the following:

• OnWindowDeinit() is called.
  • WindowCloseAnimation() is performed. This generally means that the CApplication::Render() loop is run until the close animation is finished. No user interaction happens during this phase.
  • Control states (list, thumb, scroller positions, and the currently focused control) are saved.

• FreeResources() is called.
  • Control resources are free'd and the xml file is unloaded.
  • OnWindowUnloaded() is called.

Thus, the derived classes should:

• Call the base class first so that any exit animations can be handled.
• Free any dynamically created memory in OnWindowDeinit() after having called the base class implementation.
• Anything that must be free'd after the controls etc. are out of the way should be done in OnWindowUnloaded(), after calling the base class implementation.

Extremely quick overview

Here is a short list of useful key code features in xbmc. This will only be a very quick mockup. For details refer to the code.

The Virtual File-System

One of the more elegant features of xbmc is its filesystem classes. These are all located in xbmc/FileSystem. The main interface classes here is IDirectory, IFile and IFileDirectory (virtual directories, e.g. multi-track sid files). Inheriting these we have implemented smb, local, dvd, ftp, rar, zip, xbms, xns, lastfm, shoutcast etc.

The DLL Loader

Another very important part of XBMC is it's DLL-loader. XBMC provides, for audio and video codecs which are not natively supported, the DLL loader (initially forked from the "avifile" open source project by the MPlayer developers and then forked from MPlayer to XBMC and improved by Team-XBMC). The DLL loader enables XBMC to load and use third-party made DLLs (Microsoft Windows dynamic-link library standard) adding stuff like codecs (see xbmc/cores/paplayer/ICodec.h) in DLL as well as XBMC own player players such as mplayer, paplayer, and the dvdplayer. You have defined macros to make it easy to import from a DLL, see DynamicDll?.h or e.g. DllDumb?.h for an example.

The DLL-Loader exports its own versions of the standard io functions such as fopen, fwrite, fseek etc. These versions use the xbmc filesystem. this means that anything living in dll-space can just fopen(smb://foo/bar.foo), very handy.

Settings classes

There are two of these, g_guiSettings (GUISettings.cpp) for stuff you can configure from the gui and g_stSettings (Settings.cpp?) for stuff configured from xbmc.xml. See the classes on how to add stuff (fairly easy).

Handy stuff

Lots of handy functions in CUtil (Utils.cpp?).

The media windows

Example source path: xbmc/GUIWindowVideoFiles.cpp. This is where the actual sections of xbmc are implemented. Admittingly quite a lot of code duplication going one here, but fortunately this means that taking the time to study the workings in one window will get you a very good idea how it works in the others... Key classes of interest here: CFileItem (represents files), CGUIInfoManager (the guru that knows stuff like which song is playing now etc).

To see how the windows are managed see the guilib. Key classes: CGUIWindowManager (the windowmanager that manages stuff like dialogs and windows), CGUIWindow (a window) and CGUIDialog (a dialog like yes/no etc).

Other classes of interest

IMusicInfoTagLoader – tag loaders. CStdString – our preferred string implementation Application.cpp – main code

Libraries and modules

There's a fair amount of libs used in xbmc, such as smb, rar, daap client etc or dlls such as the mp3codec. These are not a part of the main project, the source is packed in docs/ or xbmc/lib and the binaries are in cvs..

Copyright

The XBMC source code and software is licensed under the GNU General Public License (GPL). However, in order to compile the XBMC into executable form, it is currently necessary to use the Microsoft XDK (Xbox Development Kit) which is only available to licensed developers and the resulting code may only be distributed by them. Accordingly, code compiled with an unauthorized copy of the Xbox Development Kit may not be distributed legally.

XBMC provides, for audio and video codecs which are not natively supported, the DLL loader (initially forked from the "avifile" open source project by MPlayer and then from MPlayer to XBMC by Team-XBMC) can load third-party made DLLs (Microsoft Windows dynamic-link library standard) to decode unsupported formats. Where the user owns a licensed copy of the DLL, this is potentially legal. However, some third-party XBMC builds incorporate all available third-party DLLs that XBMC can support and the redistribution of those DLLs without a licence could be classified as copyright infringement.