Skip to content

docs

Jump to bottom
Javidx9 edited this page Dec 15, 2020 · 3 revisions

This is a new home page for olc::PixelGameEngine documentation. It will be migrated when mature. PGE2 Logo

Introduction

The olc::PixelGameEngine is a single file C++ header include that makes graphical application development easy. It provides a framework of easy to use, powerful rendering tools, handling all of the "boilerplate" for you, so you can focus on just creating awesome games, visualisations, demonstrations, applications and utilities that will work cross-platform, with the bare minimum setup required. For example, on Windows, it's just include and go, and on Linux and Mac, requires nothing beyond a basic C++ development install.

Every component of the olc::PixelGameEngine is designed to be easy to use, but it does not sacrifice performance. It is carefully constructed so that beginners can get graphics up and running in minutes, and the pros can exploit all sorts of features to really make fantastic and professional projects.

olc::PixelGameEngine has its roots in the older days of programming, where you concerned yourself with things at the pixel level; but provides modern, powerful utilities to make both 2D and 3D rendering a breeze. Whether you want that pixelated "indie" look, or smooth high definition quality, or both, olc::PixelGameEngine is there for you!

Why should you use it?

  1. It is already used by hundreds (if not thousands) of other programmers. It is used by professionals, beginners, hobbyists, enthusiasts, and educational establishments as a way to make programming and learning fun. You don't need to worry about libraries, SDKs, environment configurations - you just include the header file and start using graphics in your project.

  2. There is a large community of users ready to support you should you need it, with many fantastic applications and demonstrations already made. As with all OneLoneCoder output, it doesn't matter what your ability is, it's there to enable the curious to get started with something.

  3. It can run on a potato if needed. The minimum requirements are OpenGL1.0 (yes, 1.0) and C++14. Don't let this fool you into thinking it's slow and limited, take a look at any OneLoneCoder Community Showcase video and see for yourself. Frame rates are measured in 1000's of fps 😄.

  4. It does the hard work so you don't have to. It will create the window, it will draw the graphics, it will handle the input, it will refresh the screen, it handles resizing, it will configure itself for your platform and environment. You just make the magic happen!

  5. You will not be forced into a particular way of doing things. It is an engine in the sense that it will provide a loop where you do stuff. How you do that stuff is entirely up to you.

  6. It's free! It uses a very accommodating OLC-3 license. If you use the all or part of the olc::PixelGameEngine for a project, all you need to do is mention it to your end user (see exact details here).

  7. It's supported, maintained and remains backwardly compatible with earlier versions. Do not underestimate this!

Features

  • Handles flexible window creation across different operating systems
  • Provides a main "game loop" with elapsed time between frames
  • Uses transformable "layers" to composite scenes
  • Is extendable via olc::PixelGameEngine extensions
    • Sound, gamepad controllers, GUI frameworks, data sources, networking
  • Sprite resource handling
  • Geometric 2D vector manipulation
  • High speed CPU rendering - Sprites
    • Pixel level drawing routines
    • Points, lines, rectangles, circles, filled shapes, sprites, sprite sub-regions, filtering, all 32-bit colour RGBA
    • Drawing to sprites
  • High speed GPU rendering - Decals
    • Arbitrary transformations of sprites
    • Alpha-blending and lighting effects
    • Polygons
  • Text rendering
    • Built-in pixel style font
    • Mono or Proportionally spaced
  • Keyboard Input
  • Mouse Input
  • Self-configures to environment
  • Modern C++ style, yet easy to digest
  • Drawing interface presented as API
    • Can be implemented in various ways, but experience is consistent
  • Rendering subsystem is abstracted
    • OpenGL 1.0
    • OpenGL 3.3
    • GLUT
    • DirectX
    • OpenGL ES
  • Platform interface is abstracted
    • Microsoft Windows 7, 8, 10
    • Linux, ChromeOS, Raspberry Pi
    • Apple Mac
    • Even ports to PSP and Switch have been implemented!
  • Asset management and packaging tools

Hello World

#define OLC_PGE_APPLICATION
#include "olcPixelGameEngine.h"

class Example : public olc::PixelGameEngine
{
public:
    Example()
    {
        sAppName = "Example";
    }

public:
    bool OnUserCreate() override
    {
        // Called once at the start, so create things here
        return true;
    }

    bool OnUserUpdate(float fElapsedTime) override
    {
        // called once per frame
        for (int x = 0; x < ScreenWidth(); x++)
            for (int y = 0; y < ScreenHeight(); y++)
                Draw(x, y, olc::Pixel(rand() % 256, rand() % 256, rand()% 256));	
        return true;
    }
};

int main()
{
    Example demo;
    if (demo.Construct(256, 240, 4, 4))
        demo.Start();

    return 0;
}

License (OLC-3)

This is very similar to the BSD license, but there are two slight changes. You must credit OneLoneCoder in a visible way, in both source code and binary form, so if your application makes use of this code, somewhere in there it must display that you have used it. Javidx9 makes these tools with the intention that they are fun and educational, and does so for no profit at all. So far his OneLoneCoder initiative has inspired and helped thousands of programmers. It's important that derivative works reflect, and frankly advertise that this initiative exists. You can see details about how to do this here

Copyright 2018 - 2020 OneLoneCoder.com

  1. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
  2. Redistributions or derivations of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  3. Redistributions or derivative works in binary form must reproduce the above copyright notice. This list of conditions and the following disclaimer must be reproduced in the documentation and/or other materials provided with the distribution.

Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Getting Started Tutorial

Documentation

Clone this wiki locally