/* 

 *   Copyright (c) 2000, 2006 Michael J. Roberts.  All Rights Reserved. 

 *   

 *   TADS 3 Library - point of view

 *   

 *   This module provides definitions related to point of view and sensory

 *   context.  When we generate output, we do so with respect to a

 *   particular point of view; different points of view can result in

 *   different output, because of the viewer's distance from an object, for

 *   example, or because of the presence of obscuring materials between the

 *   viewer and the viewed object.  We also generate output in a particular

 *   sensory context, which controls whether or not a message that

 *   describes an object with respect to a particular sense should be

 *   generated at all; for example, if the viewer can't see an object

 *   because of darkness or an obscuring layer of material, messages about

 *   the object's visual appearance should not be generated.  

 */

/* include the library header */

#include "adv3.h"

/* ------------------------------------------------------------------------ */

/*

 *   Call a function with a given sensory context.

 *   

 *   The sensory context specifies the source of any messages generated in

 *   the course of the routine we invoke and the sense which those

 *   messages use to convey information.  If the player character cannot

 *   sense the source object in the given sense, then we block all

 *   messages generated while calling this function.

 *   

 *   If the source object is nil, this establishes a neutral sense context

 *   in which all messages are visible.

 *   

 *   This can be used for processing events that are not directly

 *   initiated by the player character, such as non-player character

 *   activities or scheduled events (fuses and daemons).  The idea is that

 *   anything described in the course of calling our routine is physically

 *   associated with the source object and relates to the given sense, so

 *   if the player character cannot sense the source object, then the

 *   player should not be aware of these happenings and thus should not

 *   see the messages.

 *   

 *   Sense contexts are not nested in their effects - we will show or hide

 *   the messages that our callback routine generates regardless of

 *   whether or not messages are hidden by an enclosing sensory context.

 *   So, this routine effectively switches to the new sense context for

 *   the duration of the callback, eliminating the effect of any enclosing

 *   context.  However, we do restore the enclosing sense context before

 *   returning, so there is no lasting net effect on the global sense

 *   context.  

 */

callWithSenseContext(source, sense, func)

{

    return senseContext.withSenseContext(source, sense, func);

}

/*

 *   Sense context output filter.  When the sense context doesn't allow

 *   the player character to sense whatever's going on, we'll block all

 *   output; otherwise, we'll pass output through unchanged.  

 */

senseContext: SwitchableCaptureFilter

    /*

     *   Recalculate the current sense context.  We will check to see if

     *   the player character can sense the current sense context's source

     *   object in the current sense context's sense, and show or hide

     *   output from this point forward accordingly.  This can be called

     *   any time conditions change in such a way that the sense context

     *   should be refigured.  

     */

    recalcSenseContext()

    {

        /* 

         *   simply invalidate the cached status; this will ensure that we

         *   recalculate the status the next time we're called upon to

         *   determine whether or not we need to block output 

         */

        cached_ = nil;

    }

    /* 

     *   Get our current blocking status.  If we've already cached the

     *   status, we'll return the cached status; otherwise, we'll compute

     *   and cache the new blocking status, based on the current sensory

     *   environment. 

     */

    isBlocking()

    {

        /* if we haven't cached the status, compute the new status */

        if (!cached_)

        {

            /* calculate the new status based on the current environment */

            isBlocking_ = shouldBlock();

            /* we now have a valid cached status */

            cached_ = true;

        }

        /* return the cached status */

        return isBlocking_;

    }

    /* our current cached blocking status, and its validity */

    isBlocking_ = nil

    cached_ = true

    /*

     *   Calculate whether or not I should be blocking output according to

     *   the current game state.  Returns true if so, nil if not.  

     */

    shouldBlock()

    {

        /*

         *   Determine if the new sense context allows messages to be

         *   displayed.  If there is no source object, we allow

         *   everything; otherwise, we only allow messages if the player

         *   character can sense the source object in the given sense.  

         */

        if (source_ == nil)

        {

            /* neutral sense context - allow messages */

            return nil;

        }

        else

        {

            /* 

             *   Determine if the player character can sense the given

             *   object.  If the source can be sensed with any degree of

             *   transparency other than 'opaque', allow the messages.  

             */

            return (libGlobal.playerChar.senseObj(sense_, source_)

                    .trans == opaque);

        }

    }

    /* invoke a callback with a given sense context */

    withSenseContext(source, sense, func)

    {

        local oldSource, oldSense;

        /* remember the old sense and source values */

        oldSource = source_;

        oldSense = sense_;

        /* set up the new sense context */

        setSenseContext(source, sense);

        /* make sure we restore the old status on the way out */

        try

        {

            /* invoke the callback */

            return (func)();

        }

        finally

        {

            /* restore the old sense context */

            setSenseContext(oldSource, oldSense);

        }

    }

    /*

     *   Set a sense context. 

     */

    setSenseContext(source, sense)

    {

        /* remember the new setings */

        source_ = source;

        sense_ = sense;

        /* calculate the new sensory status */

        recalcSenseContext();

    }

    /* the source object and sense of the sensory context */

    sense_ = nil

    source_ = nil

;

/* ------------------------------------------------------------------------ */

/*

 *   Get the current point-of-view actor - this is the actor who's

 *   performing the action (LOOK AROUND, EXAMINE, SMELL, etc) that's

 *   generating the current description.  

 */

getPOVActor()

{

    return libGlobal.pointOfViewActor;

}

/*

 *   Get the current point of view.  In *most* cases, this is the same as

 *   the point-of-view actor: the actor is looking around with its own

 *   eyes, so it's the point of view.  However, this can differ from the

 *   actor when the actor is viewing the location being described through

 *   an intermediary of some kind.  For example, if an actor is observing a

 *   remote room through a closed-circuit TV system, the point of view

 *   would be the camera in the remote room (not the TV - the point of view

 *   is intended to be the object that's physically absorbing the light

 *   rays or other sensory equivalents).  

 */

getPOV()

{

    return libGlobal.pointOfView;

}

/* get the POV actor, returning the given default if there isn't one set */

getPOVActorDefault(dflt)

{

    /* start with the global setting */

    local val = libGlobal.pointOfViewActor;

    /* if that's not nil, return it; otherwise, return the default */

    return (val != nil ? val : dflt);

}

/* get the POV, returning the given default if there isn't one set */

getPOVDefault(dflt)

{

    /* start with the global setting */

    local val = libGlobal.pointOfView;

    /* if that's not nil, return it; otherwise, return the default */

    return (val != nil ? val : dflt);

}

/*

 *   Change the point of view without altering the point-of-view stack 

 */

setPOV(actor, pov)

{

    /* set the new point of view */

    libGlobal.pointOfViewActor = actor;

    libGlobal.pointOfView = pov;

}

/*

 *   Set the root point of view.  This doesn't affect the current point of

 *   view unless there is no current point of view; this merely sets the

 *   outermost default point of view.  

 */

setRootPOV(actor, pov)

{

    local stk = libGlobal.povStack;

    /* 

     *   if there's nothing in the stacked list, set the current point of

     *   view; otherwise, just set the innermost stacked element 

     */

    if (stk.length() == 0)

    {

        /* there is no point of view, so set the current point of view */

        libGlobal.pointOfViewActor = actor;

        libGlobal.pointOfView = pov;

    }

    else

    {

        /* set the innermost stacked point of view */

        stk[1] = pov;

        stk[2] = actor;

    }

}

/*

 *   Push the current point of view

 */

pushPOV(actor, pov)

{

    /* stack the current one */

    libGlobal.povStack.append(libGlobal.pointOfView);

    libGlobal.povStack.append(libGlobal.pointOfViewActor);

    /* set the new point of view */

    setPOV(actor, pov);

}

/*

 *   Pop the most recent point of view pushed 

 */

popPOV()

{

    local stk = libGlobal.povStack;

    local len;

    /* check if there's anything left on the stack */

    len = stk.length();

    if (len != 0)

    {

        /* take the most recent element off the stack */

        libGlobal.pointOfViewActor = stk[len];

        libGlobal.pointOfView = stk[len - 1];

        /* take the actor and POV objects off the stack */

        stk.removeRange(len - 1, len);

    }

    else

    {

        /* nothing on the stack - clear the point of view */

        libGlobal.pointOfViewActor = nil;

        libGlobal.pointOfView = nil;

    }

}

/*

 *   Clear the point of view and all stacked elements

 */

clearPOV()

{

    local len;

    local stk = libGlobal.povStack;

    /* forget the current point of view */

    setPOV(nil, nil);

    /* drop everything on the stack */

    len = stk.length();

    stk.removeRange(1, len);

}

/*

 *   Call a function from a point of view.  We'll set the new point of

 *   view, call the function with the given arguments, then restore the

 *   original point of view. 

 */

callFromPOV(actor, pov, funcToCall, [args])

{

    /* push the new point of view */

    pushPOV(actor, pov);

    /* make sure we pop the point of view no matter how we leave */

    try

    {

        /* call the function */

        (funcToCall)(args...);

    }

    finally

    {

        /* restore the enclosing point of view on the way out */

        popPOV();

    }

}