Graphics 2.0: Compatibility Mode for Graphics 1.0

Updated: 2013.11.18

Overview

This guide explains how to use the Graphics 1.0 compatibility mode.

If you developed your project using the Graphics 1.0 mode (build numbers prior to 2013.2000), you can simulate most of the Graphics 1.0 behaviors in the Graphics 2.0 engine by using this V1 Compatibility Mode.

Note that new Graphics 2.0 features will not be actively supported when you run in V1 Compatibility Mode (see Limitations below).

Setting V1 Compatibility Mode

To help with the migration of existing 1.0-based code, we offer V1 Compatibility Mode, a special mode that significantly reduces the effort required to migrate. This mode is off by default. Activating it allows existing code to be run with minimal modification.

To activate it, add graphicsCompatibility = 1 to your config.lua file:

application =
{
    content =
    {
        graphicsCompatibility = 1,  -- Turn on V1 Compatibility Mode

        width = 320,
        height = 480,
        scale = "letterbox"
    },
}

When activated, the following V1 behaviors will be enabled:

You can find our legacy documentation here.

Limitations

V1 Compatibility Mode is a best effort at backwards compatibility. In many cases, things just work. However, it cannot account for every conceivable situation, so there may be situations where you need to make adjustments. Specifically, there are some changes related to the positioning of the widget.newTableView() and widget.newScrollView() widgets, even while running in compatibility mode. Because these widgets now use containers, you'll probably need to modify their positions. See Widget Considerations below.

Note that new Graphics 2.0 features will not be actively supported when you run in V1 Compatibility Mode. Even if they seem to work, there is no guarantee that they will work in future releases. Using Graphics 2.0 features while in V1 Compatibility Mode is done at your own risk.

Widget Considerations

In Graphics 2.0, the widget.newTableView() and widget.newScrollView() widgets rely on containers, so there are some positional changes required even while running in V1 Compatibility Mode.

TableView

The following changes relate to widget.newTableView():

Widget Positioning

In Graphics 2.0, the x and y properties of the table view refer to the center of the widget. This is a change from Graphics 1.0 in which the x and y properties were aligned to the top left. If you're using V1 Compatibility Mode, you will still need to make modifications to your code. In particular, you will need to re-position the table view assuming a center alignment.

Row Positioning

In Graphics 2.0, the x and y position of the rows will refer to the center of the row. If you're using V1 Compatibility Mode, you will still need to make modifications to your code. In particular, your onRowRender method will need to assume that the row group's position is in the center of the row, versus the top left as in Graphics 1.0.

Example

The following example shows how your Graphics 1.0 code might look, followed by what it should look like in Graphics 2.0 using V1 Compatibility Mode:

-- Graphics 1.0
local function onRowRender( event )
    local phase = event.phase
    local row = event.row

    -- We cache the row contentWidth and contentHeight because the row bounds can change as we add children
    local rowHeight = row.contentHeight
    local rowWidth = row.contentWidth

    local rowTitle = display.newText( row, "Row " .. row.index, 0, 0, nil, 14 )

    -- Left-align the label
    rowTitle.x = row.x - ( rowWidth * 0.5 ) + ( rowTitle.contentWidth * 0.5 )

    rowTitle.y = rowHeight * 0.5
    rowTitle:setTextColor( 0 )
end

-- Graphics 2.0 (even in V1 Compatibility Mode)
local function onRowRender( event )
    local phase = event.phase
    local row = event.row

    -- We cache the row contentWidth and contentHeight because the row bounds can change as we add children
    local rowHeight = row.contentHeight
    local rowWidth = row.contentWidth

    local rowTitle = display.newText( row, "Row " .. row.index, 0, 0, nil, 14 )

    -- Left-align the label
    rowTitle.x = 0
    rowTitle.anchorX = 0

    rowTitle.y = rowHeight * 0.5
    rowTitle:setFillColor( 0 )
end

Removed Libraries and APIs

The following libraries and APIs have been removed in Graphics 2.0 and are not available, even in V1 Compatibility Mode:

sprite library
  • The legacy sprite library has been removed. Use display.newSprite() instead.
  • If you rely on the old sprite library, a legacy sprite module is available here.
  • If your project uses Particle Candy, you must download and require() this legacy sprite module.

Open Source Frameworks

The following open source frameworks have been forked. These are not actively maintained.