<commit_before>#+TITLE:   CL-HORDE3D
#+AUTHOR:  <NAME>
#+LANGUAGE:  en
#+EMAIL:   <EMAIL>
#+DESCRIPTION: A simple CFFI wrapper for the horde3d graphics engine.
#+LANGUAGE:  en
#+OPTIONS:   H:2 num:nil toc:nil \n:nil @:t ::t |:t ^:nil -:t f:t *:t <:t

* What is CL-HORDE3D?

  A CFFI[fn:1] wrapper for the Horde3D library. Display flashy 3D graphics
  with Common Lisp.

* What is Horde3D?

  From the Horde3D[fn:2] website:

#+BEGIN_EXAMPLE
  Horde3D is a small open source 3D rendering engine. It is written in
  an effort to create a graphics engine that offers the stunning
  visual effects expected in next-generation games while at the same
  time being as lightweight and conceptually clean as
  possible. Horde3D has a simple and intuitive interface accessible
  from virtually any programming language and is particularly suitable
  for rendering large crowds of animated characters in next-generation
  quality.
#+END_EXAMPLE

  Horde3D is an OpenGL based graphics engine that does not use the
  fixed function pipeline but is built around the usage of shader
  programs. It only runs on OpenGL 2.0 compatible graphics
  hardware. It is a rather lean engine. Though it is written in C++,
  it exports a C API which can be easily wrapped.

* Dependencies

** Lisp Libraries
   - CFFI
   - Lispbuilder-sdl[fn:3] (for the examples)

** Foreign libraries
   - Horde3D
   - SDL[fn:4] (for the examples)
   
* License
  
  To make things easy, CL-HORDE3D is published under the same license
  as Horde3D: The Eclipse Public License - v 1.0.[fn:5]

* Compatibility with different Horde3D Versions

  cl-horde3d currently works together with the
  Horde3D_SDK_1.0.0-beta4. It should also run with the community svn
  version, but last time I tried the Chicago Example failed.

  There is also a horde3d-beta3-branch in the GIT repository which
  contains an older version of cl-horde3d which should run with
  Horde3D 1.0.0 beta3.
  
* Compatibility with Lisps

  CL-HORDE3D should theoretically run on all lisps that CFFI supports.
  I tested cl-horde3d with the following lisps on a amd64 Gentoo
  Linux system:

  - Clozure Common Lisp :: Works with 1.3 and 1.4.

  - Clisp :: Works with 2.48

  - SBCL :: Crashes in the foreign code. I suspect this has something
       to do with SBCLs memory model, failed allocations and no
       checks. The knight example did run with Horde3D beta3, but only
       without HDR (which means a big render target buffer).  I need
       to look into this further.
  
  I would like to hear about success or failure with other lisps and
  operating systems.

* Translating the Horde3D API from C to CL
  
  I have chosen to not translate the API literally, but to adjust the
  naming to the habits in the Common Lisp world. That's what I did:

  - I dropped the h3d prefix from all names and used a common lisp package instead.

  - I dropped all type suffixes from enum- and function names, in a
    dynamic typed language they make less sense.

  - I `lispified' all symbols (lower case with hyphens instead of camel case)

  - I dropped all -Element suffixes from the enumerations (debatable)

  - I adhered to the common-lisp tradition of not using abbreviations,
    so I renamed all occurrences of

    + 'res' to resource
    + 'mat' to 'material' (or 'matrix')
    + 'vert' to 'vertex'
    + 'elem' to 'element'
    + 'comp' to 'component'
    + 'tex' to 'texture'

* Horde3D Extensions
  
  There is code in CL-HORDE3D for the terrain and the sound
  extension, but it is totally untested and might not run at all. It
  is therefore disabled by default. The organization of source files
  for the extension will very likely change in the near future.

* Running the examples

  - Make sure you have Horde3D installed and that you can run the
    example binaries that come with it.

  - Install Lispbuilder SDL.

  - Either you symlink the top level Horde3D directory with the name
    'Horde3D' into the top level directory of cl-horde3d, or you
    adjust the *horde3d-home-directory* variable in src/examples.lisp
    to point to your Horde3D installation. The examples will load
    resources from there.

  - Load the horde3d-examples system with asdf.

  - run (horde3d-examples:knight) or (horde3d-examples:chicago) from
    the REPL. The example programs should have the same controls
    available as the original examples, but the mouse is not captured.

* Footnotes

[fn:1] http://common-lisp.net/project/cffi

[fn:2] [[http://horde3d.org]]

[fn:3] http://code.google.com/p/lispbuilder/wiki/LispbuilderSDL

[fn:4] http://www.libsdl.org

[fn:5] http://www.eclipse.org/legal/epl-v10.html

<commit_msg>Talk more about crashes with SBCL and Clisp.<commit_after>#+TITLE:   CL-HORDE3D
#+AUTHOR:  <NAME>
#+LANGUAGE:  en
#+EMAIL:   <EMAIL>
#+DESCRIPTION: A simple CFFI wrapper for the horde3d graphics engine.
#+LANGUAGE:  en
#+OPTIONS:   H:2 num:nil toc:nil \n:nil @:t ::t |:t ^:nil -:t f:t *:t <:t

* What is CL-HORDE3D?

  A CFFI[fn:1] wrapper for the Horde3D library. Display flashy 3D graphics
  with Common Lisp.

* What is Horde3D?

  From the Horde3D[fn:2] website:

#+BEGIN_EXAMPLE
  Horde3D is a small open source 3D rendering engine. It is written in
  an effort to create a graphics engine that offers the stunning
  visual effects expected in next-generation games while at the same
  time being as lightweight and conceptually clean as
  possible. Horde3D has a simple and intuitive interface accessible
  from virtually any programming language and is particularly suitable
  for rendering large crowds of animated characters in next-generation
  quality.
#+END_EXAMPLE

  Horde3D is an OpenGL based graphics engine that does not use the
  fixed function pipeline but is built around the usage of shader
  programs. It only runs on OpenGL 2.0 compatible graphics
  hardware. It is a rather lean engine. Though it is written in C++,
  it exports a C API which can be easily wrapped.

* Dependencies

** Lisp Libraries
   - CFFI
   - Lispbuilder-sdl[fn:3] (for the examples)

** Foreign libraries
   - Horde3D
   - SDL[fn:4] (for the examples)
   
* License
  
  To make things easy, CL-HORDE3D is published under the same license
  as Horde3D: The Eclipse Public License - v 1.0.[fn:5]

* Compatibility with different Horde3D Versions

  cl-horde3d currently works together with the
  Horde3D_SDK_1.0.0-beta4. It should also run with the community svn
  version, but last time I tried the Chicago Example failed.

  There is also a horde3d-beta3-branch in the GIT repository which
  contains an older version of cl-horde3d which should run with
  Horde3D 1.0.0 beta3.
  
* Compatibility with Lisps

  CL-HORDE3D should theoretically run on all lisps that CFFI supports.
  I tested cl-horde3d with the following lisps on a amd64 Gentoo
  Linux system:

  - Clozure Common Lisp :: Works with 1.3 and 1.4.

  - SBCL :: Crashes in the foreign code, in the h3dInit function,
            during OpenGL shader initialization.  There seems to be
            something wrong with the shared libs loading, perhaps I
            shouldn't load the libs at load time. The knight example
            did run with Horde3D beta3, but only without HDR (which
            means a big render target buffer).  I need to look into
            this further.
  
  - Clisp :: Crashes in foreign code.

  I would like to hear about success or failure with other lisps and
  operating systems.

* Translating the Horde3D API from C to CL
  
  I have chosen to not translate the API literally, but to adjust the
  naming to the habits in the Common Lisp world. That's what I did:

  - I dropped the h3d prefix from all names and used a common lisp package instead.

  - I dropped all type suffixes from enum- and function names, in a
    dynamic typed language they make less sense.

  - I `lispified' all symbols (lower case with hyphens instead of camel case)

  - I dropped all -Element suffixes from the enumerations (debatable)

  - I adhered to the common-lisp tradition of not using abbreviations,
    so I renamed all occurrences of

    + 'res' to resource
    + 'mat' to 'material' (or 'matrix')
    + 'vert' to 'vertex'
    + 'elem' to 'element'
    + 'comp' to 'component'
    + 'tex' to 'texture'

* Horde3D Extensions
  
  There is code in CL-HORDE3D for the terrain and the sound
  extension, but it is totally untested and might not run at all. It
  is therefore disabled by default. The organization of source files
  for the extension will very likely change in the near future.

* Running the examples

  - Make sure you have Horde3D installed and that you can run the
    example binaries that come with it.

  - Install Lispbuilder SDL.

  - Either you symlink the top level Horde3D directory with the name
    'Horde3D' into the top level directory of cl-horde3d, or you
    adjust the *horde3d-home-directory* variable in src/examples.lisp
    to point to your Horde3D installation. The examples will load
    resources from there.

  - Load the horde3d-examples system with asdf.

  - run (horde3d-examples:knight) or (horde3d-examples:chicago) from
    the REPL. The example programs should have the same controls
    available as the original examples, but the mouse is not captured.

* Footnotes

[fn:1] http://common-lisp.net/project/cffi

[fn:2] [[http://horde3d.org]]

[fn:3] http://code.google.com/p/lispbuilder/wiki/LispbuilderSDL

[fn:4] http://www.libsdl.org

[fn:5] http://www.eclipse.org/legal/epl-v10.html


{'fraction_non_alphanumeric': 0.06367949393779652, 'fraction_numerical': 0.01518186610437533, 'mean_word_length': 3.298142274580879, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1134915', 'n_tokens_mistral': 3034, 'n_tokens_neox': 2904, 'n_words': 1324}