ghost-rust/README.org

* GHOST
  Rust bindings and Rust APIs for GHOST.
 
** Layout
   ABI-compatable types and functions are all prefixed with ~GHOST_~ and are exported in the ~c~ module.
   Rust-native API variants are made as well, which have non-prefixed names.

** Notes
   Eventually we should intend to have /most/ (if not all) C compatable types either reimplemented or aliased to non-prefixed Rust types.
   At present though this is not the case, and prefixed names that can double as ergonomic Rust types are not aliased to them, so you'll have to use both often.
   The reimplementation is undergoing, the aliasing not yet.

   Leaving out implementing ~Copy~ for /most/ FFI types was a design decision, because I think the ownership model will work well here. (The hack flags-like structures need to implement copy to avoid passing around useless references when assigning them.)
   This may be changed in the future, as (virtually) all implement ~Clone~ anyway.
   I did this basically just because I want people to think about it when and why they copy something, instead of it being default behaviour. If it proves inconvenient it can be changed.

** Implementation

*** Implemented C compatable ABI
    Note: List is in-progress and doesn't show everything. (Also the checkboxes might not be rendered here.)

    - [-] ~GHOST_Types.h~
      - [X] /Handles/
        - [X] GHOST_SystemHandle
        - [X] GHOST_TimerTaskHandle
        - [X] GHOST_WindowHandle
        - [X] GHOST_EventHandle
        - [X] GHOST_RectangleHandle
        - [X] GHOST_EventConsumerHandle
        - [X] GHOST_ContextHandle
        - [X] GHOST_XrContextHandle
      - [-] /Primitives/ (ones that begin with =T= I count as `primitive')
        - [X] GHOST_TInt8
        - [X] GHOST_TUns8
        - [X] GHOST_Tint16
        - [X] GHOST_TUns16
        - [X] GHOST_Tint32
        - [X] GHOST_TUns32
        - [X] GHOST_TInt64
        - [X] GHOST_TUns64
        - [X] GHOST_TUserDataPtr
        - [X] GHOST_TSuccess
        - [X] GHOST_TTabletMode
        - [X] GHOST_TTabletAPI
        - [X] GHOST_TVisibility
        - [X] GHOST_TFireTimeConstant
        - [X] GHOST_TModifierKeyMask
        - [X] GHOST_TWindowState
        - [X] GHOST_TWindowOrder
        - [X] GHOST_TDrawingContextType
        - [X] GHOST_TButtonMask
        - [X] GHOST_TEventType
        - [ ] GHOST_TStandardCursor
        - [ ] GHOST_TKey
      - [X] /Structures/
        - [X] GHOST_GLSettings
        - [X] GHOST_GLFlags
        - [X] GHOST_DialogOptions
        - [X] GHOST_TabletData
      - [X] /Constants/
        - [X] =GHOST_TABLET_DATA_NONE= (reimpl. as ~const fn GHOST_TabletData::none()~)
    - [-] ~GHOST_C-api.h~
      - [-] /Functions/
        - [X] GHOST_CreateSystem
        - [X] GHOST_SystemInitDebug
        - [X] GHOST_DisposeSystem
        - [ ] GHOST_ShowMessageBox
      - [X] /Function pointers/
        - [X] GHOST_EventCallbackProcPtr

*** Native Rust API
    Rust native APIs are provided for things where the C API bindings are cumbersome or unsafe.
    They may or may not share ABI, if they do they will have type aliases to the corresponding ~GHOST_~ identifier, so always use those when ABI compatability is desired.
    Currently, most of the intended Rust API and structures do not exist (I haven't really studied the codebase), and C ones that are suitable for this purpose are mostly not aliased yet.

**** Overview
     List and implementation status of features

     - [-] Types
       - [X] [[Handles]]: ~handle.rs~
       - [X] [[Error handling]]: ~error.rs~
       - [ ] Events: ~event.rs~
     - [ ] Modules
       - [ ] [[System]] ~system.rs~

**** TODO System
     Provides a Rust wrapper around the GHOST system. 

**** Handles
     Handles keep the C ABI, but are re-wrtten with traits to be more idiomatic.

     The trait ~GhostHandle~ is provided, which should be implemented on a structure that is not intended to be instantiated, but instead used as a `marker' for `Handle<T>'.
     These types are ABI equivalent, and are present (with their corresponding ~GHOST_~ alias in =handle.rs=)
     Since handles are just types pointers, they are only ever used as such and shouldn't exist themselves.
***** Example
      #+BEGIN_SRC rust
        extern "C" {fn some_internal_call(window: GHOST_WindowHandle) -> GHOST_TSuccess;}

        fn do_something_to_window(window: &mut Handle<Window>) -> GhostResult<()>
        {
            unsafe {
                some_internal_call(window as GHOST_WindowHandle).into()
            }
        }
      #+END_SRC

      This trait is sealed, and we have it already implemented for all handle types, so you rarely need to use it yourself, unless as a bound where you want something to operate on or contain any type of handle.
**** Error handling
     There is provided a native Rust error handling module, with conversion and interop between the C ABI ~GHOST_TSuccess~ and the Rust ~error::GhostError~.
     There is also the type alias ~GhostResult~ provided.

     On =nightly= Rust versions, values of type ~GHOST_TSuccess~ can be propagated directly with ~?~, but on stable they must be propagated through ~GhostResult~:
     #+BEGIN_SRC rust
       extern "C" {fn returns_tsuccess() -> GHOST_TSuccess;}

       fn try_things_internal() -> GhostResult // On nightly, we can propagage `GHOST_TSuccess` directly here, but it's still more desireable for us to have a `Result<T,E>` instead of an integer in Rust, so this is still preferrable.
       {
           unsafe {
               returns_tsuccess()?;
           }

           Ok(())
       }

       fn caller()
       {
           match try_things_internal() {
               Ok(_) => println!("Yay!"),
               Err(_) => panic!("Fug"),
           }
       }
     #+END_SRC
     Keeping such a style is /usually/ preferred, anyhow.

     See [[./src/error.rs][error.rs]] for more details.

** Documentation
   Run ~cargo test; cargo doc~ and then navigate to the exported HTML in =./target/doc/ghost/index.html=.
   If you're building on stable, the documentation code samples will fail to compile. This is fine, the documentation pages will still be built all the same.