Skip to content

Latest commit

 

History

History
101 lines (71 loc) · 5.42 KB

README.md

File metadata and controls

101 lines (71 loc) · 5.42 KB
Raw

nim-csfml

Nim Bindings to Simple and Fast Multimedia Library (through CSFML).

See introduction, examples, documentation, wiki.

Warning

This library consists of class wrappers implemented as ptr object. Because Nim does not allow attaching pointers to the garbage collector, disposal of objects is not implemented and needs to be manual, by calling the destroy methods. Standard memory management caveats apply: destroying objects that are still used will break things, forgetting to destroy is a memory leak.

More details

This library is not under active development, but detailed bug reports will be given proper attention.

Introduction

nim-csfml allows you to use SFML, which is a library made in C++. So most information and tutorials for SFML revolve around C++. It is a good idea to get familiar with SFML itself first.

The API attempts to be very similar to SFML's, but some general changes are present:

  • To construct an object (sf::SomeType x(param)), use a corresponding procedure (there are 2 variations):
    • var x = newSomeType(param), which means it is a ptr object.
      • Such objects need to have destroy called to properly dispose of them.
      • Never create them using new.
    • var x = someType(param), which means it is an object (in CSFML it corresponds to a simple struct).
      • Vector2(i|f), Vector3f and (Int|Float)Rect should be created using special vec2, vec3 and rect procs.
    • Member functions, such as loadFromFile, that are used for initialization, are also represented as constructor procs described above.
  • Getter, setter functions are changed:
    • x.getSomeProperty() and x.isSomeProperty() both become x.someProperty.
    • x.setSomeProperty(v) becomes x.someProperty = v.
  • Some renames of members were necessary because of reserved words:
    • type: kind, object: obj, string: str, bind: bindGL.
  • enum names were taken from CSFML, but changed to remove their common prefix to resemble SFML's values.
    • Expect surprises in their naming. Use the documentation.
    • enums are all pure: use EnumType.Value.
    • A few enums are just represented as a list of constants, because they are not really enumerations.
    • SFML sometimes uses enum values as bitmasks. You can combine them using the | (not or) operator defined for BitMaskU32 in the util module.
  • Unicode is supported and easy to use (no need for sf::String or strange conversions):
    • CSFML's functions can deal with locale-dependent C strings (which should not be used)...
    • and UTF-32 sequences, which have been wrapped for convenient use with Nim's normal UTF-8 strings.
  • Type differences:
    • Sadly, cint and cfloat will be present everywhere, so explicit conversions to/from Nim's normal types may be required.
    • unsigned int is mapped as cint, etc., so you don't have to bother with unsigned conversions. This shouldn't cause problems, but it might.
    • The util module contains some types that provide implicit conversions.
      • For example sfBool which is defined as int, is mapped to the IntBool type with conversions to Nim's bool.
  • If you want to use some particular CSFML function but don't know what it maps to in nim-csfml, you can just search for its name in the documentation.
  • Most of the documentation is taken directly from CSFML, so don't be surprised if it talks in C/C++ terms.

See examples to learn more.

Implementation

The files private/*_gen.nim are automatically generated from CSFML's header files. They provide the base CSFML API. The files csfml_*.nim build upon them, adding compatibility with SFML API.
csfml.nim automatically imports system, window and graphics; audio should be imported separately; network is not implemented.

nim-csfml's version number (x.y.z): x.y corresponds to the supported CSFML version; z is for the project's own point releases.

Installation

nim-csfml supports CSFML 2.5; there are older releases, down to CSFML 2.1. It has been tested on Linux 64-bit.

This library can be installed using nimble install csfml.

CSFML 2.5, which requires SFML 2.5, must be installed to use it. On Windows you can just download CSFML and put the DLLs (which seem to be statically linked with SFML) in your project folder instead.

Troubleshooting

Contributing

Acknowledgements

License: zlib/libpng

This library uses and is based on SFML and CSFML.

nimrod-sfml was a great source of knowledge.

Nim and Python programming languages are used.