stl_addToNeutralImageHandles.m

function [addedImageIndices, addedImageHandles, nImages] = stl_addToNeutralImageHandles(nImages, imagesToAdd)
%% STL_ADDTONEUTRALIMAGEHANDLES - Add several images to the neutral image
% queue (ͼȫͼζ)
%
% 
%% USAGE ÷:
% ------
% [addedImageIndices, addedImageHandles] = stl_addToGlobalImageHandles(nImages, imagesToAdd)
% 
%% Input 
% ------
% nImages: The number of images to add.d
% imagesToAdd(unused): Contains the graphical content of the images to add, an 1 X
%               nImages struct that contains the following fields
%              ҪӵͼεݣΪ1 x nImages СĽṹ顣 
%               - CData
%               - AlphaData
%               - XData
%               - YData
%
%% Output :
% -------
% addedImageIndices: The indices of the image handles which contain the
%                       added images, must be an 1 x nImages (output) cell array
%                       ȫͼζУЩոձͼε±. Ϊ
%                       1 x nImages (ֵ)Ԫ
% addedImageHandles: The actual handles of these images size and type
%                       ditto
%                        ЩոձͼεľֵСͬ
% nImages: The actual number of images added, equal or lower than the input
%           nImages
%           ʵʼͼεĸضСڻֵnImages
% 
%% Dependencies ϵ:
% -------
% -- Global Variables Created:
%       none
% -- Global Variables Used:
%       queueNeutralImageHandles
%       numAvailNeutralImageHandles
%       availNeutralImageHandles
% -- Global Variables Modifed:
%       queueNeutralImageHandles
%       numAvailNeutralImageHandles
%       availNeutralImageHandles
% -- Functions Used:
%       none
%
%% Created by Mingjing Zhang, Stellari Studio, 2011.

%% Update History
%
%  Date                     Updater                 Modifications Made
% --------------            -----------------       --------------------
%  Mar 13, 2011             M. Zhang                wrote it
%  Mar 15, 2011             M. Zhang                made imagesToAdd obsolete
% --------------            -----------------       --------------------

%% --------------------Code Starts Here -------------------------

%% Declare the Global Variables ȫֱ
global queueNeutralImageHandles
global numAvailNeutralImageHandles
global availNeutralImageHandles

%% Exception Processing ⴦
% If the number of available images is smaller than the number of images to
% add, then add only the number of available images.
% ȫֶУʹõimageĿСҪӵͼĿôֻȫֶ
% Ϊֹimageʾ
nImages = min(nImages, numAvailNeutralImageHandles);

% If no image is added at all, then return immediately with empty return
% values.
% ûͼαӣôؿվ
% If not, create the return value with the given size.
% ôԤؾ
if nImages <= 0
    addedImageIndices = [];
    addedImageHandles = [];
    return;
else
    addedImageIndices = zeros(1, nImages);
    addedImageHandles = zeros(1, nImages);
end

%% Main Code

% Put nImages available handles to a temporary array.
% * Not really necessary here, but may be useful if the mechanism of
% * queueing were to be altered in a future version. 
% ҳǰnImagesõHandlesҽʱС
% * ʵһDZġĴиı˶еʵַʽ
% * ôдܾDZҪˡ
tempGlobalImageHandles = availNeutralImageHandles(1:nImages);

% -------------- Maybe it is not a good idea to initialize them here ----
% Set the properties of the images, one by one.
% % image
% % for i = 1:nImages
% %     set(queueNeutralImageHandles(tempGlobalImageHandles(i)), ...
% %         'CData', imagesToAdd(i).CData,...
% %         'AlphaData', imagesToAdd(i).AlphaData...
% %         );
% % end

% Get the indices and handles;
% ·ֵϢ
% addedImageIndices = tempGlobalImageHandles;
% addedImageHandles = queueNeutralImageHandles(tempGlobalImageHandles);

% Turn on the images added
% ʹ¼ӵimagesɼ
set(queueNeutralImageHandles(tempGlobalImageHandles), 'Visible', 'on');
addedImageIndices = num2cell(tempGlobalImageHandles);
addedImageHandles = num2cell(queueNeutralImageHandles(tempGlobalImageHandles));

% Update the number of available image handles
% ¿ͼξĿ
numAvailNeutralImageHandles = numAvailNeutralImageHandles - nImages;

% delete the used values, and pad the unused elements with zero.
% aGIHɾռõЩʣԪ㲹롣
availNeutralImageHandles(1:numAvailNeutralImageHandles) = ...
    availNeutralImageHandles((1:numAvailNeutralImageHandles)+nImages);
availNeutralImageHandles(numAvailNeutralImageHandles+1:end) = 0;
    
%% --------------- Code Ends Here --------------------------------
return;