Home Contents | # gcx:orientation | Graphics | Core4 Lua Commands

## SYNOPSIS

1. gcx:orientation(mode)
2. mode = gcx:orientation()

## DESCRIPTION

The graphics subsystem supports transparent rotation in four basic directions. When called with a value, the function changes the assumed orientation of the graphics context. When called with no arguments, the orientation is returned without change.

Changing the orientation does not modify the image that is already stored in any way. The orientation only applies a coordinate transformation so further drawing operations on the context work according to the selected value.

The orientation value 0 indicates the native orientation of the display hardware. The values 1, 2, 3 stand for 90°, 180° and 270° in clockwise direction.

Running at the native display orientation has the best performance, while all other orientations add a small speed penalty.

The properties gcx:width() and gcx:height() change depending on orientation, i.e. for orientations 1 (90°) and 3 (270°), their values are swapped with regard to the physical display hardware.

The property gcx:displayGeometry() always returns the physical display size, independently of the configured orientation.

At system startup, the kernel reads the default orientation value from kconfig.value("c4s_general", "c4t_gen_display_orientation") and initializes the framebuffer accordingly.

## EFFICIENCY ISSUES

It is possible to mix orientations at random. It is fully supported to have the framebuffer hardware running at one orientation while having an image loaded into a buffer at a different orientation. Blitting between such buffers works as intended.

When mixing different orientations that way, however, the system has to fall back to generic code that is not speed optimized.

It is therefore recommended to run all image buffers and the framebuffer at the same orientation, unless an orientation change is explicitly required by the application.

## NOTES

The touch screen, if present, has its own orientation setting. It is initialized to the same value as the framebuffer at startup. Should application code change the framebuffer orientation at runtime, it must also change the touch screen orientation to match. This is done by calling tch:orientation().

## RETURN VALUE

The configured orientation value.

## ERRORS

Raises an error if gcx is not a graphics context or if mode is not a valid value.

## EXAMPLE

> >
fb = gfx.open() print (fb:orientation())
0

## SEE ALSO

gcx:width, gcx:height, gcx:displayGeometry, tch:orientation