Camera Legacy

This is legacy documentation

Current Wiki index can be found here

By default the scene class uses a static view to render the scene. The camera component allows you to control the view via an entity in the scene graph. For example if you want the view to follow a player attach a camera component to either the player entity, or one of its children. When attaching the camera make sure you save the pointer returned by the addComponent() function, and set the scene's active camera with it.

xy::Camera::Ptr camera = xy::Component::create<xy::Camera>(messageBus, view);
xy::Camera* camPtr = entity->addComponent(camera);
scene.setActiveCamera(camPtr);

Cameras are created with an instance of the active message bus (as are all components) and a reference view of the scene. The reference view sets the initial size and viewport of the camera's view. The position and rotation are ignored, as they will be applied from the parent entity's transform. The initial view is usually best set to the default view of the current state's context, when using the StateStack, as it is initialised to properly match the current resolution and aspect ratio of the window. The view can be reset at any time using setView(). To return to using the scene's default camera set the active camera to nullptr. This is done automatically by xygine when camera components are destroyed while active.

Camera components have a few properties which can be adjusted to influence their behaviour:

void lockTransfrom(Camera::TransformLock, bool locked);

This function allows locking one or more transform properties of the camera. For instance lockTransform(TransformLock::AxisY, true) will prevent the camera moving vertically. This could be useful in a side scrolling game where you need the camera to move left and right with the player, but not bob up and down when she jumps. lockTransform(TransformLock::AxisY, false) will unlock the vertical axis again. In a top-down racer you might want the camera to follow the player in both axes, but not allow the camera to rotate as the player turns. This can be achieved with TransformLock::Rotation.

void lockBounds(const sf::FloatRect& bounds, bool lock);

lockBounds() will make the camera stay within the defined bounds if lock is true. In cases where a player can walk to the edge of a map it is sometimes desirable to stop the camera following the player near the edges, so that the outside of the map is not displayed. The function automatically accounts for the size of the camera's view, so the supplied FloatRect should be the same size as the map to which you want the camera bound.

void setZoom(float);

You can set the zoom of the camera as a ratio of the reference view supplied when creating the camera or via setView(). A value of 1 is normal zoom, 2 makes everything twice as big, and 0.5 will zoom out so everything is half the size, for example. Zoom values must be greater than 0, and it should be noted that zoom does not heed the bounds value if the camera has its lockBounds value set to true, so zooming out may reveal the edges of a map. This is also the inverse of the normal behaviour of an SFML view, where a factor of 2 makes things appear half the size.

void setViewport(const sf::FloatRect&);

Setting the viewport defines how much of the screen is covered by the camera. This is explained in the SFML documentation. The viewport property is useful for rendering split screen games or multiple views at once. If using PostProcess effects which do not require letterboxing then setting the viewport to 0,0,1,1 will repair any double letterboxing (appearing as squashed images) which may occur.

void setClearColour(const sf::color&)

Setting the clear colour of a camera defines which colour a post process buffer is cleared to, before being drawn on. Right now, there's not much use for this.