Skip to content

jacereda/glcv

Repository files navigation

GLCV

1 Purpose

GLCV is a small canvas/event handling library that provides a thin layer abstracting the details of configuring the canvas and handling input. Sort of a simple GLUT/SDL. No API is provided for sound/fonts/widgets, there are good solutions out there for those and freedom of choice is a good thing.

2 Building

2.1 IOS

The following command should build the library and the examples and install them in the IOS simulator directory.

./mk-ios

2.2 Android

The following command should build the library and the examples and install them in the Android emulator. The emulator must be running.

./mk-android

2.3 NPAPI

The following command should build the library and the examples and install them in the user’s plugins directory.

./mk-npapi

After building, try opening file:testplugin.html

2.4 Xlib

To compile the test application, use this command

./mk-xlib

2.5 Cocoa

To compile the test application, use this command

./mk-cocoa

Or if you prefer to test the ARC version

./mk-cocoa-arc

2.6 Windows

To compile the test application, use this command

mk-win

3 API

3.1 Functions

3.1.1 Application hook

intptr_t event(const ev * e);

This is the event handling routine implemented by your application.

3.1.2 Application control

void cvQuit();

Call this to terminate your application.

3.1.3 Canvas queries

unsigned cvWidth();

Current canvas width

unsigned cvHeight();

Current canvas height

3.1.4 Canvas control

void cvFullscreen();

On platforms that support it, put the canvas in fullscreen mode.

void cvWindowed();

On platforms that support it, put the canvas in windowed mode.

3.1.5 Mouse queries

int cvMouseX();

Current X mouse position

int cvMouseY();

Current Y mouse position

3.1.6 Mouse control

void cvSetCursor(const uint8_t * rgba, int hotx, int hoty);

On platforms that support it, set the mouse cursor bitmap. The rgba argument is a pointer to a 32*32*4 bytes array containing 32x32 RGBA pixels.

void cvHideCursor();

On platforms that support it, hide the mouse cursor.

void cvDefaultCursor();

On platforms that support it, establish the default mouse cursor.

3.1.7 Keyboard queries

int cvPressed(cvkey key);

True if key is currently pressed

int cvReleased(cvkey key);

True if key has just been released

3.1.8 Keyboard control

void cvShowKeyboard();

On platforms that support it, show the on-screen keyboard

void cvHideKeyboard();

On platforms that support it, hide the on-screen keyboard

3.1.9 Logging

void cvReportV(const char * fmt, va_list ap);

Report a message (depending on the platform, it might go to a file).

void cvReport(const char * fmt, ...);

Report a message (depending on the platform, it might go to a file).

3.1.10 Events

int evType(const ev *);

Event type.

const char * evName(const ev *);

Event name.

int evWidth(const ev *);

Width for CVE_RESIZE events.

int evHeight(const ev *);

Width for CVE_RESIZE events.

cvkey evWhich(const ev *);

Keycode associated to CVE_DOWN/CVE_UP events.

int evX(const ev *);

Mouse X position for CVE_DOWN/CVE_UP events.

int evY(const ev *);

Mouse Y position for CVE_DOWN/CVE_UP events.

int evArgC(const ev *);

Argument count for CVE_INIT events.

char ** evArgV(const ev *);

Argument array for CVE_INIT events.

intptr_t evArg0(const ev *);

First event argument, mostly internal.

intptr_t evArg1(const ev *);

Second event argument, mostly internal.

intptr_t cvInject(cveventtype, intptr_t, intptr_t);

Inject an event, mostly internal.

const char * keyName(cvkey);

Key name for CVE_DOWN/CVE_UP events.

3.2 Events

3.2.1 CVE_NONE

Null event, must be ignored.

3.2.2 CVE_INIT

Called upon initialization, no GL operations should be performed at this stage.

3.2.3 CVE_TERM

Called before terminating the application.

3.2.4 CVE_GLINIT

The OpenGL context has been established. Might be called several times.

3.2.5 CVE_GLTERM

The OpenGL context is going to be destroyed. Might be called several times.

3.2.6 CVE_UPDATE

This is your update routine, should be called at ~60Hz.

3.2.7 CVE_RESIZE

Called when the canvas is resized. Might be called several times.

3.2.8 CVE_DOWN

A key/button has been pressed.

3.2.9 CVE_UP

A key/button has been released.

3.2.10 CVE_UNICODE

Called when the user enters text.

3.2.11 CVE_MOTION

The mouse moved.

3.2.12 CVE_CLOSE

The application is about to close.

3.2.13 CVE_INVOKE

Invoke method. The argument is available as evMethod().

3.3 Queries

3.3.1 CVQ_NAME

Return the desired application name.

3.3.2 CVQ_LOGGER

Function to be used for logging. The returned function prototype should be:

void report(const char * appname, const char * string);

3.3.3 CVQ_XPOS

Return the desired X position. This is just a hint and can be ignored on some platforms.

3.3.4 CVQ_YPOS

Return the desired Y position. This is just a hint and can be ignored on some platforms.

3.3.5 CVQ_WIDTH

Return the desired width. Note that this is a hint and can be ignored on some platforms. Your code should use the width reported via CVE_RESIZE or ask explicitly with cvWidth().

3.3.6 CVQ_HEIGHT

Return the desired height. Note that this is a hint and can be ignored on some platforms. Your code should use the height reported via CVE_RESIZE or ask explicitly with cvHeight().

4 Examples

4.1 Simple example that just draws

4.2 Complete example handling all queries/events

5 License

Copyright (c) 2011-2012, Jorge Acereda Maciá All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the author 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 OWNER 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.