# \*\*\*\*\*NOTICE\*\*\*\*\* 

This repo is not under active development anymore and has been archived. Continued development has been migrated to [Pixel2](https://github.com/gopxl/pixel). A big thank you to [faiface](https://github.com/faiface) for creating this awesome library and for all the hard work put into it. We encourage old and new users to check out the new repo and contribute to it.



<p align="center"><img src="logo/LOGOTYPE-HORIZONTAL-BLUE.png"></p>

# Pixel [![Build Status](https://travis-ci.org/faiface/pixel.svg?branch=master)](https://travis-ci.org/faiface/pixel) [![GoDoc](https://godoc.org/github.com/faiface/pixel?status.svg)](https://godoc.org/github.com/faiface/pixel) [![Go Report Card](https://goreportcard.com/badge/github.com/faiface/pixel)](https://goreportcard.com/report/github.com/faiface/pixel) [![Join the chat at https://gitter.im/pixellib/Lobby](https://badges.gitter.im/pixellib/Lobby.svg)](https://gitter.im/pixellib/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Discord Chat](https://img.shields.io/discord/699679031603494954)](https://discord.gg/q2DK4MP)  

A hand-crafted 2D game library in Go. Take a look into the [features](#features) to see what it can
do.

```
go get github.com/faiface/pixel
```

If you are using Modules (Go 1.11 or higher) and want a mutable copy of the source code:

```
git clone https://github.com/faiface/pixel # clone outside of $GOPATH
cd pixel
go install ./...
```

See [requirements](#requirements) for the list of libraries necessary for compilation.

All significant changes are documented in [CHANGELOG.md](CHANGELOG.md).

## Tutorial

The [Wiki of this repo](https://github.com/faiface/pixel/wiki) contains an extensive tutorial
covering several topics of Pixel. Here's the content of the tutorial parts so far:

- [Creating a Window](https://github.com/faiface/pixel/wiki/Creating-a-Window)
- [Drawing a Sprite](https://github.com/faiface/pixel/wiki/Drawing-a-Sprite)
- [Moving, scaling and rotating with Matrix](https://github.com/faiface/pixel/wiki/Moving,-scaling-and-rotating-with-Matrix)
- [Pressing keys and clicking mouse](https://github.com/faiface/pixel/wiki/Pressing-keys-and-clicking-mouse)
- [Drawing efficiently with Batch](https://github.com/faiface/pixel/wiki/Drawing-efficiently-with-Batch)
- [Drawing shapes with IMDraw](https://github.com/faiface/pixel/wiki/Drawing-shapes-with-IMDraw)
- [Typing text on the screen](https://github.com/faiface/pixel/wiki/Typing-text-on-the-screen)
- [Using a custom fragment shader](https://github.com/faiface/pixel/wiki/Using-a-custom-fragment-shader)

## [Examples](https://github.com/faiface/pixel-examples)

The [examples](https://github.com/faiface/pixel-examples) repository contains a few
examples demonstrating Pixel's functionality.

**To run an example**, navigate to it's directory, then `go run` the `main.go` file. For example:

```
$ cd pixel-examples/platformer
$ go run main.go
```

Here are some screenshots from the examples!

| [Lights](https://github.com/faiface/pixel-examples/blob/master/lights) | [Platformer](https://github.com/faiface/pixel-examples/blob/master/platformer) |
| --- | --- |
| ![Lights](https://github.com/faiface/pixel-examples/blob/master/lights/screenshot.png) | ![Platformer](https://github.com/faiface/pixel-examples/blob/master/platformer/screenshot.png) |

| [Smoke](https://github.com/faiface/pixel-examples/blob/master/smoke) | [Typewriter](https://github.com/faiface/pixel-examples/blob/master/typewriter) |
| --- | --- |
| ![Smoke](https://github.com/faiface/pixel-examples/blob/master/smoke/screenshot.png) | ![Typewriter](https://github.com/faiface/pixel-examples/blob/master/typewriter/screenshot.png) |

| [Raycaster](https://github.com/faiface/pixel-examples/blob/master/community/raycaster) | [Gizmo](https://github.com/Lallassu/gizmo) |
| --- | --- |
| ![Raycaster](https://github.com/faiface/pixel-examples/blob/master/community/raycaster/screenshot.png) | ![Gizmo](https://github.com/Lallassu/gizmo/blob/master/preview.png) |

## Features

Here's the list of the main features in Pixel. Although Pixel is still under heavy development,
**there should be no major breakage in the API.** This is not a 100% guarantee, though.

- Fast 2D graphics
  - Sprites
  - Primitive shapes with immediate mode style
    [IMDraw](https://github.com/faiface/pixel/wiki/Drawing-shapes-with-IMDraw) (circles, rectangles,
    lines, ...)
  - Optimized drawing with [Batch](https://github.com/faiface/pixel/wiki/Drawing-efficiently-with-Batch)
  - Text drawing with [text](https://godoc.org/github.com/faiface/pixel/text) package
- Audio through a separate [Beep](https://github.com/faiface/beep) library.
- Simple and convenient API
  - Drawing a sprite to a window is as simple as `sprite.Draw(window, matrix)`
  - Wanna know where the center of a window is? `window.Bounds().Center()`
  - [...](https://godoc.org/github.com/faiface/pixel)
- Full documentation and tutorial
- Works on Linux, macOS and Windows
- Window creation and manipulation (resizing, fullscreen, multiple windows, ...)
- Keyboard (key presses, text input) and mouse input without events
- Well integrated with the Go standard library
  - Use `"image"` package for loading pictures
  - Use `"time"` package for measuring delta time and FPS
  - Use `"image/color"` for colors, or use Pixel's own `color.Color` format, which supports easy
    multiplication and a few more features
  - Pixel uses `float64` throughout the library, compatible with `"math"` package
- Geometry transformations with
  [Matrix](https://github.com/faiface/pixel/wiki/Moving,-scaling-and-rotating-with-Matrix)
  - Moving, scaling, rotating
  - Easy camera implementation
- Off-screen drawing to Canvas or any other target (Batch, IMDraw, ...)
- Fully garbage collected, no `Close` or `Dispose` methods
- Full [Porter-Duff](http://ssp.impulsetrain.com/porterduff.html) composition, which enables
  - 2D lighting
  - Cutting holes into objects
  - Much more...
- Pixel let's you draw stuff and do your job, it doesn't impose any particular style or paradigm
- Platform and backend independent [core](https://godoc.org/github.com/faiface/pixel)
- Core Target/Triangles/Picture pattern makes it easy to create new drawing targets that do
  arbitrarily crazy stuff (e.g. graphical effects)
- Small codebase, ~5K lines of code, including the backend [glhf](https://github.com/faiface/glhf)
  package

 ## Related repositories

 Here are some packages which use Pixel:
 - [TilePix](https://github.com/bcvery1/tilepix) Makes handling TMX files built with [Tiled](https://www.mapeditor.org/) trivially easy to work with using Pixel.
 - [spriteplus](https://github.com/cebarks/spriteplus) Basic `SpriteSheet` and `Animation` implementations
 - [PixelUI](https://github.com/dusk125/pixelui) Imgui-based GUIs for Pixel
 - [pixelutils](https://github.com/dusk125/pixelutils) Variety of game related utilities (sprite packer, id generator, ticker, sprite loader, voronoia diagrams)

## Missing features

Pixel is in development and still missing few critical features. Here're the most critical ones.

- ~~Audio~~
- ~~Drawing text~~
- Antialiasing (filtering is supported, though)
- ~~Advanced window manipulation (cursor hiding, window icon, ...)~~
- Better support for Hi-DPI displays
- Mobile (and perhaps HTML5?) backend
- ~~More advanced graphical effects (e.g. blur)~~ (solved with the addition of GLSL effects)
- Tests and benchmarks
- Vulkan support

**Implementing these features will get us to the 1.0 release.** Contribute, so that it's as soon as
possible!

## Requirements

If you're using Windows and having trouble building Pixel, please check [this
guide](https://github.com/faiface/pixel/wiki/Building-Pixel-on-Windows) on the
[wiki](https://github.com/faiface/pixel/wiki).

[PixelGL](https://godoc.org/github.com/faiface/pixel/pixelgl) backend uses OpenGL to render
graphics. Because of that, OpenGL development libraries are needed for compilation. The dependencies
are same as for [GLFW](https://github.com/go-gl/glfw).

The OpenGL version used is **OpenGL 3.3**.

- On macOS, you need Xcode or Command Line Tools for Xcode (`xcode-select --install`) for required
  headers and libraries.
- On Ubuntu/Debian-like Linux distributions, you need `libgl1-mesa-dev` and `xorg-dev` packages.
- On CentOS/Fedora-like Linux distributions, you need `libX11-devel libXcursor-devel libXrandr-devel
  libXinerama-devel mesa-libGL-devel libXi-devel libXxf86vm-devel` packages.
- See [here](http://www.glfw.org/docs/latest/compile.html#compile_deps) for full details.

**The combination of Go 1.8, macOS and latest XCode seems to be problematic** as mentioned in issue
[#7](https://github.com/faiface/pixel/issues/7). This issue is probably not related to Pixel.
**Upgrading to Go 1.8.1 fixes the issue.**

## Contributing

Join us in the [Discord Chat!](https://discord.gg/q2DK4MP)

Pixel is in, let's say, mid-stage of development. Many of the important features are here, some are
missing. That's why **contributions are very important and welcome!** All alone, I will be able to
finish the library, but it'll take a lot of time. With your help, it'll take much less. I encourage
everyone to contribute, even with just an idea. Especially welcome are **issues** and **pull
requests**.

**However, I won't accept everything. Pixel is being developed with thought and care.** Each
component was designed and re-designed multiple times. Code and API quality is very important here.
API is focused on simplicity and expressiveness.

When contributing, keep these goals in mind. It doesn't mean that I'll only accept perfect pull
requests. It just means that I might not like your idea. Or that your pull requests could need some
rewriting. That's perfectly fine, don't let it put you off. In the end, we'll just end up with a
better result.

Take a look at [CONTRIBUTING.md](CONTRIBUTING.md) for further information.

## License

[MIT](LICENSE)


Pixel

3D engine for the Go language, works on Windows and Linux ([Harfang on Go.dev](https://github.com/harfang3d/harfang-go)).

<img src="https://github.com/harfang3d/image-storage/raw/main/brand/logo_harfang3d_owl_only.png" align="right" width="200"/>

# HARFANG® 3D engine

[![PyPI](https://img.shields.io/pypi/v/harfang)](https://pypi.org/project/harfang)
[![Downloads](https://static.pepy.tech/badge/harfang)](https://pepy.tech/project/harfang)
[![Downloads](https://static.pepy.tech/badge/harfang/month)](https://pepy.tech/project/harfang)

HARFANG®3D is an all-in-one 3D visualization library usable in C++, Python, Lua and Go.
#### Table of contents

1. [About](#section_1)
    - [Features](#subsection_1a)
    - [Screenshots](#subsection_1b)
2. [Download](#section_2)
3. [Building the SDK](#section_3)
    - [Prerequisites](#subsection_3a)
    - [Building](#subsection_3b)
4. [Using the C++ SDK](#section_4)
5. [Version](#section_5)
6. [License](#section_6)
7. [Contribute](#section_7)
8. [Support Harfang](#section_8)

<a name="section_1"></a>
# About

HARFANG®3D is an easy-to-adapt, cross-platform, multi-language, powerful and optimized solution to integrate with embedded systems, into existing environments and combining features to meet the industrial standards of real-time 3D imaging.

The HARFANG®3D architecture makes it easy to meet the requirements for hardware integration, display performance and security.

HARFANG®3D is written in C++ and is based on the open-source bgfx library supporting Vulkan, Metal, DirectX (from 9 to 12), OpenGL and OpenGL ES. It Builds on Windows, Linux, Intel and ARM.

<a name="subsection_1a"></a>
## Features

Platforms supported
* Win32 and Win64 Intel
* Linux 64 Intel
* Aarch 64 ARM

Scene API
* Node & component based
* Performance oriented

Rendering pipeline
* Low-spec PBR rendering pipeline
* High-spec 'AAA' rendering pipeline (screen space GI & reflection)
* Support of user pipeline shaders

VR API
* XR support via OpenXR
* VR support via OpenVR/SteamVR including Eye tracking (SRanipal)
* Tested with the HTC Vive/Vive Pro, Valve Index, Lenovo Explorer, Oculus Rift S, Oculus Quest 2, Varjo XR-3

Physics API
* Rigid bodies, collisions, mechanical constraints, ray casting

Audio API
* Play/stream WAV/OGG formats
* 3D audio spatialization

Languages supported
* C++
* Python _(3.2+)_
* Lua _(5.4)_
* Go _(1+, experimental)_
<a name="subsection_1b"></a>
## Screenshots

The following screenshots were captured on a 1080GTX in 1080P running at 60FPS.

![alt text](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/2.0.111/sun_temple_aaa.png)

![alt text](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/2.0.111/sun_temple_aaa_2.png)

*(Sun Temple, courtesy of the Open Research Content Archive (ORCA))*

<a name="section_2"></a>
# Download

You can download the HARFANG binaries from the official website:
https://dev.harfang3d.com/releases

<a name="section_3"></a>
# Build the SDK

<a name="subsection_3a"></a>
## Prerequisites

* Git
* CMake 3.19+
* CPython 3.2+
* Go 1+ _(for Harfang Go module)_
* Doxygen _(for Harfang C++ SDK documentation)_
* Autodesk FBX SDK _(for FBX Converter)_

### Windows
* Visual Studio 2019 _(C++ compiler and IDE)_
* MinGW _(for Harfang Go module)_

### Linux
* GCC 9 or above
* CLang 

<a name="subsection_3b"></a>
## Building

1. Clone the `Harfang 3D` repository including its submodules.
    ```
    git clone --recursive -j8 https://github.com/harfang3d/harfang3d.git
    cd harfang3d
    ```

1. Create build directory. Note that the described directory layout is not mandatory.
    ```
    mkdir build
    cd build
    ``` 

1. Clone Fabgen.
    ```
    git clone https://github.com/ejulien/FABGen.git
    ```

1. Download and install Autodesk FBX SDK.

1. Create a directory that will hold the build system generated by CMake.
    ```
    mkdir cmake
    cd cmake
    ```

1. Generate the build system using CMake. For example, on Windows it will be:
    ```
    cmake ../.. -G "Visual Studio 16 2019" -A x64 \
        -DCMAKE_INSTALL_PREFIX:PATH="D:/harfang/build/install" \
        -DPYTHON_EXECUTABLE:FILEPATH="C:/Python36/python.exe" \
        -DHG_FABGEN_PATH:PATH="D:/harfang/build/fabgen" \
        -DHG_FBX_SDK:PATH="D:/fbx_sdk" 
    ``` 

    * `CMAKE_INSTALL_PREFIX` specifies the directory where the Harfang SDK will installed.
    * `PYTHON_EXECUTABLE` is the path the Python 3 interpreter.
    * `FABGEN_PATH` is the path to Fabgen binding generator.
    * `HG_FBX_SDK` is the path to Autodesk FBX SDK.

    &nbsp;    
    Here is the list of available CMake options.

    * __C++ SDK__
        * `HG_BUILD_CPP_SDK` : Build C++ SDK (default: __OFF__).
        * `HG_BUILD_TESTS`   : Build C++ SDK unit tests (default: __OFF__).
        * `HG_BUILD_DOCS`    : Build API and C++ SDK documentations (default: __OFF__).
        * `HG_ENABLE_BULLET3_SCENE_PHYSICS` : Enable Bullet physics API (default: __ON__).
        * `HG_ENABLE_RECAST_DETOUR_API` : Enable Recast/Detour navigation mesh and path finding API (default: __ON__).
        * `HG_ENABLE_OPENVR_API`   : Enable OpenVR API (default: __OFF__).
        * `HG_ENABLE_SRANIPAL_API` : Enable VIVE Eye and Facial Tracking SDK (SRanipal) API (default: __OFF__).
    * __Tools__
        * `HG_BUILD_ASSETC`             : Build AssetC asset compiler (default: __ON__).
        * `HG_BUILD_ASSIMP_CONVERTER`   : Build Assimp based 3D model converter (default: __ON__).
        * `HG_BUILD_FBX_CONVERTER`      : Build FBX converter (default: __ON__).
        * `HG_BUILD_GLTF_IMPORTER`      : Build GLTF importer (default: __ON__).
        * `HG_BUILD_GLTF_EXPORTER`      : Build GLTF exporter (default: __ON__).
    * __Bindings__
        * `HG_BUILD_HG_LUA`     : Build Harfang LUA module (default: __OFF__).
        * `HG_BUILD_HG_PYTHON`  : Build Harfang Python module (wheel) (default: __OFF__).
        * `HG_BUILD_HG_GO`      : Build Harfang GO module (default: __OFF__).
        
    &nbsp;    

1. Build the SDK.
    ```
    cmake --build . --config Release --target INSTALL
    ```
    _Note: On Linux you will need to explicitly specify the build type with `-DCMAKE_BUILD_TYPE=Release`_  

    Depending on the set of option passed to CMake the install directory will contain the following subdirectories:
    * `cppsdk` : Harfang C++ SDK.
    * `hg_python` : Harfang Python module.
    * `hg_lua` : Harfang LUA module.
    * `hg_go` : Harfang Go module.
    * `assetc` : Asset compiler.
    * `assimp_converter` : Assimp 3D model converter.
    * `fbx_converter` : FBX converter.
    * `gltf_importer` : GLTF importer.
    * `gltf_exporter` : GLTF exporter.
    
### Notes on Visual Studio Code

1. Install the CMakeTools extension.

1. Copy the `harfang/.vscode/template_settings.json` file to `harfang/.vscode/settings.json` and edit it to reflect your local installation.

1. Open the `harfang` folder in Visual Studio Code. CMakeTools should succesfully configure the project.

<a name="section_4"></a>
# Use the SDK

The Harfang C++ SDK directory `cppsdk` contains the following:
* `bin` : depending on the configuration used, this directory contains either a `Release` or `Debug` subdirectory with all the shared libraries.
* `lib` : like the `bin` directory, it contains a subdirectories named after the configuration used during build (`Release` or `Debug`) with all the generated static libraries.
* `include` : contains all the C++ include files of Harfang public API.
* `cmake` : contains the CMake configuration files. 

To add the Harfang C++ SDK to your CMake project, just add the following to the `CMakeLists.txt` file:
```cmake
find_package(harfang REQUIRED
    COMPONENTS cppsdk
    PATHS ${HG_CPPSDK_PATH}
    NO_DEFAULT_PATH
)
```
with `HG_CPPSDK_PATH` the path to the `cppsdk` directory. For example, if we follow the directory layout given above, it will be `D:/harfang/build/install/cppsdk`.

Targets should link against the following libraries.
* `hg::engine` 
* `hg::foundation` 
* `hg::platform`
* `hg::libluadll`

The `install_cppsdk_dependencies` function installs the Harfang C++ SDK shared libraries dependencies.
```cmake
install_cppsdk_dependencies(destination component)
```
* `destination` : is the library where the shared libraries will be installed.
* `component` : installation component name.

<a name="section_5"></a>
# Version

Harfang follows the Semantic Versioning Specification (SemVer) (http://semver.org).

Given a version number MAJOR.MINOR.PATCH, increment the:

* MAJOR version when you make incompatible API changes,
* MINOR version when you add functionality in a backwards-compatible manner, and
* PATCH version when you make backwards-compatible bug fixes.

<a name="section_6"></a>
# License

Harfang is licensed under the GPLv3, LGPLv3 and a commercial license:<br>
https://www.harfang3d.com/license

<a name="section_7"></a>
# Contribute
## Contributor License Agreement

By contributing your code to HARFANG you grant the [HARFANG3D organization](https://www.harfang3d.com/en_US/legal) a non-exclusive, irrevocable, worldwide, royalty-free, sublicenseable, transferable license under all of Your relevant intellectual property rights (including copyright, patent, and any other rights), to use, copy, prepare derivative works of, distribute and publicly perform and display the Contributions on any licensing terms, including without limitation:
(a) open source licenses like the MIT license; and (b) binary, proprietary, or commercial licenses. Except for the licenses granted herein, You reserve all right, title, and interest in and to the Contribution.

You confirm that you are able to grant us these rights. You represent that You are legally entitled to grant the above license. If Your employer has rights to intellectual property that You create, You represent that You have received permission to make the Contributions on behalf of that employer, or that Your employer has waived such rights for the Contributions.

You represent that the Contributions are Your original works of authorship, and to Your knowledge, no other person claims, or has the right to claim, any right in any invention or patent related to the Contributions. You also represent that You are not legally obligated, whether by entering into an agreement or otherwise, in any way that conflicts with the terms of this license.

The [HARFANG3D organization](https://www.harfang3d.com/en_US/legal) acknowledges that, except as explicitly described in this Agreement, any Contribution which you provide is on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.

<a name="section_8"></a>
# How to support Harfang?

There are numerous ways to help Harfang grow its community:

* Give the repository a [Star :star:](https://github.com/harfang3d/harfang3d)
* Purchase a license of [Harfang Studio](https://www.harfang3d.com/en_US/studio)
* Subscribe to Harfang [Youtube channel](https://www.youtube.com/c/HARFANG3D/videos)
* Follow us on [Twitter](https://twitter.com/harfang3dengine/)
* Leave a Comment/Like on [Alternative To](https://alternativeto.net/software/harfang-3d/about/)

<a name="section_9"></a>
# More screenshots...

![Nvidia USD Attic](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.2.6/attic_harfang.png)

*(The NVIDIA USD Attic using the HARFANG 3D AAA renderer)*

![ORCA Sun Temple](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.1.1/sun_temple_aaa.png)

![ORCA Sun Temple](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.1.1/sun_temple_aaa_2.png)

*(Sun Temple, courtesy of the Open Research Content Archive (ORCA))*

![ORCA Bistro](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.1.1/cafe_exterior_aaa.png)

![ORCA Bistro](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.1.1/cafe_exterior_aaa_2.png)

*(Bistro, courtesy of the Open Research Content Archive (ORCA))*

![Sponza Atrium](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.1.1/sponza_atrium_aaa.png)

![Sponza Atrium](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.1.1/sponza_atrium_aaa_2.png)

*(Sponza Atrium GLTF, courtesy of Crytek/Themaister)*

![alt text](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.2.6/marine-melodies-screenshot_1280.png)

*(Marine Melodies, by Resistance Norway)*



The Best Go Libraries For Game Development - Awesome game development libraries. (2)

Pixel

Harfang3D