Android: What's the difference between lockCanvas() and lockCanvas(null)?

Question

The title says it quite clearly, though I'll give a code example just in case. This is from the LunarLander sample in the Android SDK:

    @Override
    public void run() {
        while (mRun) {
            Canvas c = null;
            try {
                c = mSurfaceHolder.lockCanvas(null);
                synchronized (mSurfaceHolder) {
                    if (mMode == STATE_RUNNING) updatePhysics();
                    doDraw(c);
                }
            } finally {
                // do this in a finally so that if an exception is thrown
                // during the above, we don't leave the Surface in an
                // inconsistent state
                if (c != null) {
                    mSurfaceHolder.unlockCanvasAndPost(c);
                }
            }
        }
    }

The documentation for lockCanvas() says all pixels must be re-drawn, whereas lockCanvas(Rect dirty) says you're only required to re-draw pixels in dirty. I see two possible interpretations of passing null to this function: it doesn't require any pixels to be re-drawn, or behaves in the same manner as lockCanvas().

Answer 1

It is open source

public Canvas lockCanvas() {
  return internalLockCanvas(null);
}
public Canvas lockCanvas(Rect dirty) {
  return internalLockCanvas(dirty);
}