Internet TV Source

This document describes part of Internet TV source, mainly the video and user interface Tcl/Tk modules.

CVS Info: $Id: itvsource.html,v 1.7 1997/04/28 12:38:47 tsalste Exp $

    Status:
    New = Introduced in ITV
    Modified = Modified in ITV
    

Modules listed

This module includes the user interface of the channel selection window.
Module Status Description
cf-main.tcl Modified Starts itv
ui-main.tcl Modified The user interface of the channel selection window, plus channel list functions
ui-windows.tcl Modified Includes part of the user interface of the TV/video window.
tv-window.tcl New Creates part of the user interface of the TV/video window created in ui-windows.tcl
brightness.tcl New Brightness settings interface in the TV window
volume.tcl New Volume interface in the TV window
audio.tcl New Audio control functions for interface between itv and itv-audio
profile.tcl New Module for reading/writing user settings to file itv.ini
shortcut.tcl New Creates and manages the channel list on the TV window
confbus.tcl ?
cf-network.tcl Modified Procedures for opening connections on different kinds of networks
cf-tm.tcl ? (tm means title-maker)
cf-util.tcl Modified Collection of various utility procedures
entry.tcl Default bindings for entry widgets (entry widget is the same as a text box control in other environments)
tkerror.tcl Modified Procedures for showing error messages
ui-ctrlmenu.tcl Modified Contains the vic channel control dialog window (which was removed in itv) and some utility procedures (in use by itv).
ui-extout.tcl External output control functions
ui-h261_play.tcl Routines for playing H.261 video.
ui-resource.tcl Fonts. Various default settings with [option add].
ui-srclist.tcl Source list window. Not in use (?)
ui-stats.tcl Statistics. May not be in use.
ui-switcher.tcl Handles the video switcher abstraction. Generic objects are registered as swithable with a method to call back when switching occurs. By using a generic callback mechanism, this code is shared between the on screen windows and external video outputs.
ui-unix.tcl proc run_resource_dialog (user settings) for unix
ui-vdd.tcl Several routines initialized by vdd_main.
ui-win32.tcl proc run_resource_dialog (user settings) for Win32
vw.tcl VideoWindow object used to implement video widgets in Tcl.

Module details

cf-main.tcl

This module starts itv.
Procedure Status Description
vic_main Modified The Tcl part of itv starts here

ui-main.tcl

This module includes the user interface of the channel selection window.
Procedure Status Description
session { args } Evaluates "$V(session) $args"
build.bar { w } Modified Builds the widgets for the bottom bar frame (.bar) of the channel list
itv_help New Builds and shows a help window
lookup_visual Look through the list of available visuals, and choose the best one that the program supports
init_visual { w } Modified Initialize the visual, colormap, and dither global variables based on X resources, available visuals, etc.
init_color Initialize the colormodel
shorttime { seconds } New Formats $seconds in human readable format
init_channel_details { w } New Creates widgets for showing channel details (description, time, WWW) at the bottom of the channel list
show_channel_details { w channel_index } New Shows channel details in $w.details for channel of index $channel_index after a channel has been selected
show_www New Runs netscape to open the WWW page for the selected channel
init_gui Modified Build the user-interface of the channel window. Does not build everything, but calls other procs.
add_active { src } Sets active($src)=1 and creates stamp grid if necessary. Called by really_activate.
rm_active { src } deactivates a source by unsetting active($src), and destroys the stamp grid if necessary. Called by deactivate in ui-main.cc.
periodic_update Modified Updates the channel preview picture once in a second
set_rate_vars Not in use
select_thumbnail { w src } Called when use clicks on thumbnail video window.
update_source_info { src } Updates arrays src_info, src_nickname, and src_name with source channel data
adjust_voff { win d } Hack to get rid of ugly borer when displaying CIF sized images in a NTSC sized windows
attach_renderer { src w } Create a renderer for window $w and attach it to $src. Called by decoder_changed, change_format, attach_window in ui-main.tcl. Calls "[$src handler] attach $target". Sets win_target($w) to [new assistor $fmt].
detach_renderer { src w } Calls "[$src handler] detach $win_target($w)", unsets and deletes win_target($w)
attach_window { src w } Bind a source to a window so that the video stream from source $src appears in widget $w. Sets win_src($w) and appends to win_list($src). Calls attach_renderer. attach_window is called for both the stamp video window (by build.src) and the big TV window.
detach_window { src w } Opposite to attach_window
window_highlight { w color } Sets the background color of $w and its children to $color
set_background { w color } Sets the background color of $w to $color
build.src { w src color } Modified Creates a preview picture for $src in the channel window $w. Calls attach_window to attach source to the preview picture.
bump Increases V(curcol) or if V(ncol) is met, sets V(curcol) to 0 and increases V(currow). Called by redecorate.
redecorate { n } Arranges the sources for the active channel.
create_decoder { src } Creates a decodor source $src and sets it to $src's handler.
activate { src } Modified Add a src to the active senders list. Make a postage stamp window. Calls "create_decoder $src". Sets V(itv_src) to $src. Sets pending call to "really_activate $src". Called by Source::activate in source.cc.
really_activate { src } Modified Happens 1 second after activate. Calls "add_active $src", "build.src $w $src 1". Sets last_open_channel_src to $src.
update_decoder { src } Calls set_rate_vars and update_source_info.
change_format { src } Calls detach_renderers and then attach_renderer for $src, and a number of other procs too. Calls "extout_attach_src $src [extout_detach_src $src]" (not in ui-main.tcl).
decoder_changed { d } Called when the video stream state changes in a way that would affect the choice of renderer.
detach_renderers { src } Calls detach_renderer for each window in win_list($src).
change_name { src } Modified Apparently called when the name of $src has changed. Sets window names by using windowname in ui-windows.tcl (which doesn't change the name because it's fixed to "Internet TV".
deactivate { src } Modified Remove a src from the active senders list. Calls destroy_userwin and detach_window.
update_rate src Sets statistics to arrays ftext btext ltext fpshat bpshat lhat shat, indexed by $src.
update_src { src } Happens once in a second, calls update_rate and update_source_info.
info_text { src } Returns an info string for $src.
init_channel_list New Initializes controls on the channel list window
itv_adios Modified Quits audio and video. Calls adios.
close_channel New Closes the channel being viewed. Calls quit_TV, "srctab delete $V(itv_src)", and deletes V(data-net), V(ctrl-net), and V(session). Sets V(channel-open) to 0.
open_new_channel { address } New Opens a channel at $address. Calls close_channel, init_network, init_late. Sets running to 1.
select_channel { y } New User clicked a channel in the list -> select it

Opening a source

Opening a source video is complicated. Here is what happens on the Tcl side.

PacketHandler* Source::activate (source.cc) calls "activate $src" (ui-main.tcl) to open a source. activate creates a decoder with "create_decoder $src".

After waiting for idle, "really_activate $src" (ui-main.cc) is called. really_activate quits from itself if there is already one source active, that is, only one source can be active at a time. really_activate calls "add_active $src" to set active($src)=1 and to create some widgets if this is the first source to activate in this channel.

After this, really_activate creates user interface widgets for the video stamp, and calls "build.src $V(grid).$src $src 1". Then it calls "update_decoder $src". build.src calls attach_window (ui-main.tcl) to bind the source to the stamp video window. attach_window calls attach_renderer to create a renderer and attach it to $src, and it also calls "[$src handler] attach $target" to do that.

Closing a source

close_channel (ui-main.tcl) is called by open_new_channel to close the current video and audio channels. close_channel calls quit_TV to close the TV window if it's open. Then it calls srctab delete $V(itv_src), closes and deletes ctrl-net and data-net, and last deletes $V(session). deactivate calls "rm_active $src". It also disables audio by calling audio_stop. deactivate is called by close_channel and also when the user presses "d" with mouse over the video stamp. source.cc calls it too. "rm_active $src" unsets active($src) and destroys a grid widget if no more sources are open.

Widget hierarchy in the channel selection window

.

.channel_list (frame)
.channel_list.list (listbox)
.channel_list.scroll

.top 
.top.bar (bottom bar -side bottom)
.top.bar.title "ITV v#.# - ohtace@tcm.hut.fi"
.top.bar.quit

.top.details (frame)
.top.details.descriptionframe
.top.details.descriptionframe.description
.top.details.descriptionframe.scrollbar
.top.details.timeframe
.top.details.timeframe.time (label for showing time)
.top.details.timeframe.picture (clock)
.top.details.timeframe.www (button)

.top.label (removed in ITV)
(hierarchy description not complete)

ui-windows.tcl

This module includes part of the user interface of the TV/video window.
Procedure Status Description
destroy_userwin { w } Destroy a viewing window but remember where it was and what size it was
resize { vw w h } Resize a video window. Calls detach_renderer and attach_renderer in ui-main.tcl.
viewing_window { w } True if w is a top-level viewing window (name starts as ".vw")
window_set_slow { w } Slows (or stops?) video
reallocate_renderer { w } Delete and create a new renderer on window $w without changing anything else
create_video_widget { w width height } Create a video widget (as implemented in vw.cc) and initialize all the global state associated with a window.
stop_video { videowidget } New Checks if the video is still running, and stops it by calling detach_window.
quit_TV { videowidget } New Closes the TV window. Calls stop_TV. Unsets TVWindow.
stop_TV { videowidget } New Stops video and audio in the TV window. Doesn't close the window. Calls stop_video.
open_window { src } Modified Opens a TV window for viewing video. Creates a new window if none exists by calling create_TV_window, uses TVWindow otherwise. Calls attach_window to bind the source to the window.
create_TV_window { src } Modified Create a new window for viewing video. Creates widgets. Calls init_tv_gui in tv-window.tcl. Calls attach_window to bind the source to the window.
configure_tv { videoctrl width height } New Used to catch the configure event and resize the TV window.
configure_tv { videoctrl width height } Modified Used to catch the configure event and resize the TV window. Calls proc resize in ui-windows.tcl.
windowname { w name } Modified Names a window "Internet TV". Parameter "name" is ignored.
window_switch { w src } Changes the source of a TV window
window_set_switched { w } Calls switcher_enable / switcher_disable according to win_is_switched($w)
window_set_timed { w } Calls switcher_set_timer / switcher_cancel_timer according to win_is_timed($w)

Widget hierarchy in the TV window window

Base name .vw1 etc., let's call it $tv

$tv
$tv.frame
$tv.frame.video (video widget, implemented in C++)

$tv.bottom (bottom bar, frame)
$tv.bottom.volumecontrols
$tv.bottom.volumecontrols.volume (canvas for "V" picture)
$tv.bottom.volumecontrols.topbuttons
$tv.bottom.volumecontrols.topbuttons.mute
$tv.bottom.volumecontrols.topbuttons.speaker
$tv.bottom.volumecontrols.volumebuttons (frame form up/down buttons)
$tv.bottom.volumecontrols.volumebuttons.volumeup
$tv.bottom.volumecontrols.volumebuttons.volumedown

$tv.bottom.brightnesscontrols
$tv.bottom.brightnesscontrols.brightpicture ("the sun", canvas)
$tv.bottom.brightnesscontrols.brightness (bar, canvas)
$tv.bottom.brightnesscontrols.up
$tv.bottom.brightnesscontrols.down


$tv.bottom.shortcutarea
$tv.bottom.shortcutarea.channels (menubutton)
$tv.bottom.shortcutarea.channels.menu (menu)

$tv.bottom.shortcutarea.dismiss
(hierarchy description not complete)

tv-window.tcl

This module creates part of the user interface of the TV/video window. New in ITV.
Procedure Status Description
init_tv_gui {window} New Creates new ITV widgets for the TV window. $window is a window created in ui-windows.tcl. Calls build_volume, build_brightness, and build_shortcut.

brightness.tcl

Brightness settings interface in the TV window. New in ITV.

Module interface

Procedure Status Description
build_brightness {window} New Builds the brightness controls on $window.
set_brightness {br level} New Calls updategamma to set the gamma correction (brightness) level
updategamma { s } Modified Sets the gamma correction level by calling "$V(colorModel) gamma $s" which in turn calls ColorModel::command in color.cc. $s is the new gamma correction level.

Global array, used in brightness.tcl only:

bright()   Initialized in init_brightness
           Includes various predefined and run-time settings

audio.tcl

This module communicates with itv-audio.
Procedure Status Description
audio_start New Interface to start itv-audio. Takes as arguments multicast address and port from which audio should be received.
audio_stop New Interface to stop itv-audio. Sends exit command to itv-audio. Can be safely called even if itv-audio is not running.
setvolume New Interface to send volume commands to itv-audio.
audio_sock_accept New Serverside callback to be called by tcl eventloop when itv-audio connects to itv socket.
audio_readSock New Called by tcl eventloop, when there is data ready to be read.

volume.tcl

Volume interface in the TV window. New in ITV.

Module interface

Procedure Status Description
build_volume {window} New Builds the volume controls on $window.
set_volume {volume level} New Calls setvolume in audio.tcl to adjust volume level.

Global array, used in volume.tcl only:

volume()   Initialized in init_volume
           Includes various predefined and run-time settings

profile.tcl

Module for reading/writing user settings to file itv.ini. New in ITV.

Module interface

get_profile name                          Returns value for setting "name",
                                          "" if "name" not set
get_profile_default name default          Like get_profile but returns default
                                          if "name" not set
get_profile_range name start end default  Like get_profile_default but returns lues between
                                           start..end, else default
get_profile_boolean name default          Like get_profile_default but returns only true/false
set_profile name value                    Sets name=value and writes to the ini file
unset_profile name                        Clears the setting name and writes to the ini file
write_profiles                            Writes the settings to $inifilename

shortcut.tcl

Creates and manages the channel list on the TV window. New in ITV.

Module interface

Procedure Status Description
build_shortcut { window } New Builds the channel list controls on $window.
add_shortcut { name id } New Adds a channel to the channel list.
show_shortcut_channel_name { channelname } New Displays channelname on the channel menu button.
show_shortcut_channel { channel_index } New Displays the name of the channel (at channel_index) on the channel menu button. Calls show_shortcut_channel_name.
select_shortcut_channel { channel_index } New Switches to the channel at channel_index.
show_channel_selection { advertid } New Selects a channel on the channel selection window

Global arrays:

short()    Initialized at the beginning of the module
           Includes various predefined and run-time settings
short(max_recent_channels) = How many channels to show
short(channels)            = How many channels there are on the list
short(channels_shown)      = How many channels were displayed in the menu
short(menubutton)          = Points to the menu button widget

short_channel_name()    
           Set by add_shortcut
           Channel names indexed from 1 to short(max_recent_channels)
           Index 1 is the oldest channel on the list

Global variables and arrays

Variable Status Description
V Modified Array of settings:
V(class)         "Vic"
V(app)           "itv"
V(media)         "video"
V(channel-open)  New in ITV, 0 or 1, not needed ? 
                 Unset by close_channel.
V(session)       Session object
V(sessionType)   One of rtp, rtpv2, vat, vic, nv, ivs
V(grid)          ".top.grid" (frame) if 
                 there are active sources
V(colorModel)    ?
V(colormap)      ?
V(curcol)        ?
V(ncol)          ?
V(currow)        ?
V(itv_src)       Active video source (new in ITV)
                 Set by activate in ui-main.tcl
V(ctrl-net)      Set in net_open_xxx in cf-network.tcl 
                 to point to a network object
V(data-net)      Set in net_open_xxx in cf-network.tcl
                 to point to a network object
V(useHardwareDecode)

V(audio-addr)    New in ITV: Address of audio stream. 
                 Set by select_channel_advertid. 
                 Unset if there is no audio.
V(audio-port)    New in ITV: Port of audio stream. 

V(capwin)
V(cb)
V(confname)
V(dither)
V(encoder)
V(encrypt)
V(gamma)          Gamma (brightness) correction 
                        (see brightness.tcl)
V(grabber)
V(muteNewSources)
V(optionsMenu)
V(visual)

V(TVWindow)      New in ITV
                 Points to the currently open TV window. 
                 Set by create_TV_window,
                 unset by quit_TV in ui-windows.tcl.

V(show-preview)  New in ITV - Set to 1 to show the 
                 video stamp window in the channel list
www_page New URL for the selected channel. 0 or "" if there is no URL.
active($src) 1 if $src is active, doesn't exist if it isn't. Set by add_active, unset by rm_active in ui-main.tcl. [array size active] gives the number of active sources.
running New 1 if itv is running. Set by open_new_channel. Unset by close_channel.
src_info($src), src_nickname($src), src_name($src) Source channel information, set by update_source_info in ui-main.tcl
win_target($w) Set by attach_renderer to [new assistor $fmt]
Unset by detach_renderer
win_is_slow($w) ?
win_use_hw($w) Use hardware decode
win_list($src) List of TV windows by source. "win_list $src" may contain the video stamp widget and the TV window video widget in list form. Set by attach_window, unset by detach_window in ui-main.tcl.
win_is_switched($w) ?
win_is_timed($w) ?
win_src($w) Source for window $w. Set by attach_window, unset by detach_window in ui-main.tcl.
last_open_channel_src New Channel source that was last opened. Set by really_activate.
ftext btext ltext fpshat bpshat lhat shat (all arrays indexed by $src) Apparently statistics for sources. Not really needed in ITV, but referred to in the code. Set by update_rate, unset by deactivate in ui-main.tcl.
itv_debug New If this has value 1, itv prints a LOT of debug messages. Itv-audio also creates file .itv-audio-debug to current directory. Controlled by -i command line flag (see main.cc).
audio_running New Has value 1, if itv-audio is running
audio_command_sock New Socket, through which commands are send to itv-audio
audio_channel_list New hash, key is channel name, value is multicast address
video_channel_list New hash, key is channel name, value is multicast address
media_channel_list New array, value is "audiovideo" if this session sends both and either "audio" or "video" in other cases
channel_id_list New array, value is the name of the channel

ohtace@tcm.hut.fi
Last modified: Mon Apr 28 14:24:07 EEST 1997