S3GE API Specification [Draft 1.0]

By Frankie Taylor

Overview

S3GE features a modular, scaleable, interchangeable Plug-in architecture inspired by TGC's DBPro Plug-in System and derived from Black Box and White Box software engineering concepts. A typical Function demonstrates the basic principle of a Black|White Box as it can take arguments (Input) and can return a value (Output). DLLs & Static Libraries are examples of a Black Box, in which you're provided their Function's I/O, but cannot view their internal workings. An example of a White Box would be a Open Source Lib in which inner workings of it's Functions are viewable.

Similar to TGE Plug-ins for DBPro, a S3GE `Plug-in` is a self contained system that provides a feature or function "on demand". As a self contained system, a Plug-in can be used indepenently in other projects. A Plug-in can come in the form of a DLL/Static Library (Black Box) or DGDK/C++ Open Source Library (White Box). Each Plug-in must provide: 1) A formatted Set of Commands to initialize|modify|update|terminate objects created and managed by the Plug-in; 2) Full Documentation for Input/Output on each Command Function.

S3GE API is implemented as a Gray Box, which is a managed Wrapper System for Black|White Box Plug-ins. The basic concept behind a Gray Box is to provide one I/O to (n)Black|White Boxes. Also, one Gray Box can virtually merge the funtionality of two or more Black|White Boxes. Motivations behind the Gray Box are to: 1) Simplify Source Code Management and Contribution; 2) Support Modular Expandability; 3) Minimize Work Flow Dependencies; 4) Simplify the Interface to the Engine Core; 5) Register Core Functions to the Scripting Engine.

The Super 3D Game Engine Core is built entirely with Gray Boxes and all Systems are implemented with Plug-ins. Gray Boxes support Plug-in addition/removal/interchangeability by modifying the only the internals of the Gray Box. The I/O's are left intact requiring no alteration. Gray Boxes also make use of Function Overloading to achieve interchangeability. Its expected that with a Modular design, new Systems will be built on top of existing systems and Plug-in dependencies will occur. When developing such systems in S3GE its required that Gray Box Command calls be used in place of direct Plugin Commands calls to ensure Plug-in interchangeability an manageability.

Gray Boxes are soley controlled and managed by the DOSP Core Team. As a managed system, Gray Boxes adhere to even stricter Plug-in Rules: 1) Provide Gray Box Command for each Plug-in Command; 2) Use Standardized Naming Convention & Namespace for Gray Box Command Sets; 3) Full Documentation for each Gray Box Command stored in a Centralized Respository. Following suit with DBPro Plug-in's Formatted Commands, Gray Boxes use Integer IDs to reference individual instances of Plug-in objects, sub-objects, DGDK objects, etc. Thus, Integer IDs are often passed to Gray Boxes and returned. With Standards in place, Open Source contributors can develop Plug-in's based on anticipated I/O requirements.

Name Convention

  1. Namespace

    All Gray Box Constructs are encapsulated in the Namespace: `S3GE`

  2. Command Name

    Command is defined as any Method or Function pertaining to a specific Plugin.

    1. All Commands names are all lowercase.
    2. All #DEFINE, Constants, and Enum Values are all upppercase.
    3. Reference Designators are all uppercase:
    4. Container Names are followed by name of container type.
    5. Command Name Format: Systemname [Subsystem] Objectname [Typename][Subtype...][Propertyname][Subproperty...] Verb

      Example: uigizmocreate

      System Names

      • core(common)
      • ui
      • physics
      • renderer
        • image
        • texture
        • shader
      • file
      • script
      • network
      • logic
      • registry
      • particle
      • audio
    6. Verbs

    7. Command Parameter Names

Comments

  1. LGPL Copy Permission Statement is required at top of Library:

    /*
    This program is free software: you can redistribute it and/or modify
    it under the terms of the Lesser GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
    
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    Lesser GNU General Public License for more details.
    
    You should have received a copy of the Lesser GNU General Public License
    along with this program.  If not, see http://www.gnu.org/licenses/.
    */
    
  2. Comments within Gray Box Ccnstructs adhere to the Doxygen documentation blocks for C++ Code.
    Reference: Doxygen documentation blocks.
  3. Command Help Summary Format

    All Commands provides a Help Summary that includes Description, Input, Output. The summary is located at the very top function defintion prior to any statements.

    Example(Doxygen Doc block format):

    int S3G::uigizmocreate(int parentID, int behaviorID, float x, float y, float width, float height){
    	/*!
    	* Description: Creates UI Gizmo
    	* Plug-in: MAUI by Techlord
    	* Command: int gizmocreate(int parentID, int behaviorID, float x, float y, float width, float height)
    	* -Input:
    	*	-# parentID parent gizmo reference ID, inheriting style & behavior
    	*	-# behaviorID reference ID for Behavior Profile
    	*	-# x - starting screen horizontal position
    	*	-# y - starting screen vertical position
    	*	-# width - gizmo width
    	*	-# height - gizmo height
    	* Output: returns reference ID
    	*/
    
    	//plug-in
    	MAUI::gizmo ui = New MAUI::gizmocreate(parentID, behaviorID, x, y, width, height);
    	return ui.ID;
    }